@weppy/roblox-mcp 1.4.2 → 1.5.0

package/docs/ko/README.md

@@ -56,7 +56,15 @@ AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해
 - Basic: Studio -> Local 단방향 동기화
 - Pro: 양방향 동기화 + 타입별 Direction/Apply Mode + 변경 기록 + 멀티 Place
 
-### 3) Roblox Explorer: VSCode에서 Studio 계층 구조 탐색
+### 3) Playtest: AI가 테스트를 자동으로 실행하고 검증
+
+Studio 플레이테스트를 AI가 직접 제어합니다. F5(Play)/F8(Run) 시작/중지는 물론, 테스트 스크립트를 주입하고 로그를 수집해 리포트까지 자동 생성합니다.
+
+- "Run 모드로 플레이테스트 시작하고, NPC가 목표 지점까지 이동하는지 확인해줘."
+- "SpawnLocation이 지면 위에 있는지 테스트 스크립트를 작성해서 자동 실행해줘."
+- "방금 수정한 스크립트가 에러 없이 동작하는지 플레이테스트로 검증해줘."
+
+### 4) Roblox Explorer: VSCode에서 Studio 계층 구조 탐색
 
 Roblox Studio의 전체 인스턴스 트리를 VSCode 안에서 바로 확인할 수 있습니다. 서비스를 탐색하고, 동기화된 스크립트와 속성 파일을 열고, 동기화 상태를 추적하세요 — Studio로 전환할 필요 없이.
 
@@ -76,12 +84,21 @@ Roblox Studio의 전체 인스턴스 트리를 VSCode 안에서 바로 확인할
 ## 세부 문서
 
 - [설치 가이드](../en/installation/README.md)
-- [Tool 지원 범위](../en/tools/overview.md)
-- [Sync 기능 상세 가이드](../en/sync/overview.md)
+- [Tool 전체 목록](tools/overview.md)
+- [Sync 기능 상세 가이드](sync/overview.md)
 - [Roblox Explorer (VSCode 확장)](installation/roblox-explorer.md)
 - [호환성](../compatibility.md)
 - [문제 해결 가이드](../troubleshooting.md)
 
+### 기능별 도구 가이드
+
+- [인스턴스 & 속성](tools/instances-and-properties.md) — 검색, 생성, 수정, 태그
+- [스크립트 & 코드 실행](tools/scripting.md) — 스크립트 관리, Luau 실행
+- [월드 환경](tools/world-and-environment.md) — 조명, 지형, 카메라
+- [에셋 & 오브젝트 연출](tools/assets-and-effects.md) — 모델 삽입, 트윈, 이펙트
+- [플레이테스트 & 자동 테스트](tools/playtest.md) — 플레이테스트 제어, 자동 검증
+- [시스템 & 디버깅](tools/system-and-debugging.md) — 연결, 로그, 배치 실행
+
 ## Pro로 업그레이드
 
 양방향 Sync, 고급 제작 기능, AI 토큰 효율 — 한 번의 업그레이드로 모두 누리세요.

package/docs/ko/tools/assets-and-effects.md

@@ -0,0 +1,104 @@
+# 에셋 & 오브젝트 연출
+
+> 에셋 삽입, 트윈 애니메이션, 오디오, 파티클 이펙트, 물리 충돌 그룹을 관리합니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `manage_assets` | Pro | Creator Store 검색, 모델/패키지 삽입, 에셋 정보 |
+| `manage_tween` | Pro | 트윈 생성, 재생, 일시정지, 취소 |
+| `manage_animation` | Pro | 애니메이션 로드, 재생, 정지, 트랙 조회 |
+| `manage_audio` | Pro | 사운드 재생/정지/일시정지, 오디오 리스너 설정 |
+| `manage_effects` | Pro | 파티클 방출, 초기화, 토글 |
+| `manage_physics` | Pro | 충돌 그룹 등록, 충돌 여부 설정 |
+
+## 주요 워크플로우
+
+### 에셋으로 씬 구성
+
+```
+"Creator Store에서 '나무' 모델을 검색해서 Workspace에 3개 배치해줘"
+```
+
+`manage_assets`의 `search_insert`로 검색과 삽입을 한 번에 처리합니다.
+
+### 인터랙티브 연출
+
+```
+"문을 클릭하면 3초에 걸쳐 열리는 트윈을 만들어줘"
+```
+
+`manage_tween`의 `create`로 트윈을 정의하고 `play`로 재생합니다. 동시에 `manage_audio`의 `play`로 문 여는 효과음을 추가합니다.
+
+### 파티클 + 사운드 조합
+
+```
+"보스 등장 시 폭발 파티클과 함께 효과음을 재생해줘"
+```
+
+`manage_effects`의 `emit`으로 파티클을 방출하고, `manage_audio`의 `play`로 사운드를 동시에 재생합니다.
+
+## 액션 레퍼런스
+
+### Manage Assets (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `insert` | 에셋 ID로 모델 삽입 | Pro |
+| `info` | 에셋 메타데이터 가져오기 | Pro |
+| `search` | Creator Store 검색 | Pro |
+| `search_insert` | 검색하여 첫 번째 일치 항목 삽입 | Pro |
+| `insert_free` | 무료 모델 삽입 | Pro |
+| `insert_package` | 패키지 삽입 | Pro |
+| `export` | 현재 선택 내보내기 | Pro |
+
+### Manage Tween (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `create` | 대상 속성을 가진 트윈 생성 | Pro |
+| `play` | 생성된 트윈 재생 | Pro |
+| `pause` | 실행 중인 트윈 일시정지 | Pro |
+| `cancel` | 트윈 취소 | Pro |
+
+### Manage Animation (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `load` | Humanoid/AnimationController에 애니메이션 로드 | Pro |
+| `play` | 로드된 애니메이션 트랙 재생 | Pro |
+| `stop` | 재생 중인 애니메이션 정지 | Pro |
+| `get_tracks` | 로드된 모든 애니메이션 트랙 나열 | Pro |
+
+### Manage Audio (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `play` | 사운드 재생 (필요시 Sound 생성) | Pro |
+| `stop` | 재생 중인 사운드 정지 | Pro |
+| `pause` | 재생 중인 사운드 일시정지 | Pro |
+| `resume` | 일시정지된 사운드 재개 | Pro |
+| `set_listener` | 오디오 리스너 타입/대상 설정 | Pro |
+
+### Manage Effects (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `emit` | ParticleEmitter에서 파티클 방출 | Pro |
+| `clear` | 모든 파티클 초기화 | Pro |
+| `toggle` | 효과 활성화 또는 비활성화 | Pro |
+
+### Manage Physics (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `register_group` | 충돌 그룹 등록 | Pro |
+| `set_collidable` | 두 그룹이 충돌할 수 있는지 설정 | Pro |
+| `get_groups` | 등록된 모든 충돌 그룹 나열 | Pro |
+
+## 관련 문서
+
+- [인스턴스 & 속성](instances-and-properties.md) — 오브젝트 생성 및 배치
+- [월드 환경](world-and-environment.md) — 조명, 지형, 카메라
+- [도구 전체 목록](overview.md)

package/docs/ko/tools/instances-and-properties.md

@@ -0,0 +1,104 @@
+# 인스턴스 & 속성
+
+> Roblox Studio의 인스턴스를 검색, 생성, 수정하고 속성/어트리뷰트/태그를 관리합니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `query_instances` | 혼합 | 인스턴스 검색, 계층 탐색, 클래스 정보 조회 |
+| `mutate_instances` | 혼합 | 인스턴스 생성, 삭제, 복제, 이동 |
+| `manage_properties` | 혼합 | 속성 읽기/쓰기, 어트리뷰트, 태그 관리 |
+
+## 주요 워크플로우
+
+### 씬 구조 파악
+
+```
+"Workspace 아래 모든 Part를 검색해서 위치와 크기를 알려줘"
+```
+
+`query_instances`의 `search_class`로 Part를 찾고, `manage_properties`의 `mass_get`으로 Position/Size를 일괄 조회합니다.
+
+### 오브젝트 배치
+
+```
+"맵 중앙에 SpawnLocation 4개를 정사각형으로 배치하고 TeamColor를 각각 다르게 설정해줘"
+```
+
+`mutate_instances`의 `mass_create`로 한 번에 생성한 뒤, `manage_properties`의 `mass_set`으로 속성을 일괄 설정합니다.
+
+### 태그 기반 관리
+
+```
+"'Collectible' 태그가 붙은 모든 오브젝트를 찾아서 Anchored를 true로 바꿔줘"
+```
+
+`manage_properties`의 `get_tagged`로 태그 인스턴스를 조회하고, `mass_set`으로 속성을 변경합니다.
+
+## 액션 레퍼런스
+
+### Query Instances (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `get` | 경로로 인스턴스 속성 가져오기 | Basic |
+| `children` | 직계 자식 또는 모든 자손 가져오기 | Basic |
+| `find_child` | 이름과 선택적 클래스 필터로 첫 번째 자식 찾기 | Basic |
+| `find_descendant` | 이름으로 첫 번째 자손 찾기 | Basic |
+| `wait_for_child` | 자식이 나타날 때까지 대기 (타임아웃 포함) | Basic |
+| `class_info` | 클래스 정보 및 유효한 속성 가져오기 | Basic |
+| `search_name` | 이름 패턴으로 인스턴스 검색 (와일드카드 지원) | Basic |
+| `search_class` | 클래스 이름으로 인스턴스 검색 | Basic |
+| `file_tree` | 루트에서 파일 트리 구조 가져오기 | Pro |
+| `project_structure` | 전체 프로젝트 구조 가져오기 | Pro |
+| `descendants` | 인스턴스의 모든 자손 가져오기 | Pro |
+| `ancestors` | 인스턴스의 모든 조상 가져오기 | Pro |
+| `search_property` | 속성 값으로 인스턴스 검색 | Pro |
+| `search_tag` | 태그로 인스턴스 검색 | Pro |
+
+### Mutate Instances (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `create` | 새 인스턴스 생성 | Basic |
+| `create_with_props` | 초기 속성을 가진 인스턴스 생성 | Basic |
+| `delete` | 인스턴스 삭제 | Basic |
+| `clone` | 인스턴스 복제 | Basic |
+| `move` | 인스턴스를 새 부모로 이동 | Basic |
+| `rename` | 인스턴스 이름 변경 | Basic |
+| `pivot` | 피벗 위치 또는 CFrame 설정 | Basic |
+| `create_tree` | 계층적 인스턴스 트리 생성 | Pro |
+| `mass_create` | 여러 인스턴스 한 번에 생성 | Pro |
+| `mass_delete` | 여러 인스턴스 삭제 | Pro |
+| `mass_duplicate` | 여러 인스턴스 복제 | Pro |
+| `smart_duplicate` | 간격과 개수를 지정하여 복제 | Pro |
+
+### Manage Properties (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `get` | 단일 속성 값 가져오기 | Basic |
+| `set` | 단일 속성 값 설정 | Basic |
+| `get_all` | 인스턴스의 모든 속성 가져오기 | Basic |
+| `set_multiple` | 여러 속성 한 번에 설정 | Basic |
+| `get_attr` | 어트리뷰트 값 가져오기 | Basic |
+| `set_attr` | 어트리뷰트 값 설정 | Basic |
+| `get_all_attrs` | 모든 어트리뷰트 가져오기 | Basic |
+| `delete_attr` | 어트리뷰트 삭제 | Basic |
+| `add_tag` | 인스턴스에 태그 추가 | Basic |
+| `remove_tag` | 인스턴스에서 태그 제거 | Basic |
+| `check_tag` | 인스턴스가 태그를 가지고 있는지 확인 | Basic |
+| `get_tags` | 인스턴스의 모든 태그 가져오기 | Basic |
+| `get_tagged` | 특정 태그를 가진 모든 인스턴스 가져오기 | Basic |
+| `set_calculated` | 수식을 사용하여 속성 설정 | Pro |
+| `set_relative` | 현재 값을 기준으로 상대적으로 속성 설정 | Pro |
+| `mass_set` | 여러 인스턴스에 속성 설정 | Pro |
+| `mass_get` | 여러 인스턴스에서 속성 가져오기 | Pro |
+| `modify_children` | 부모의 모든 자식 수정 | Pro |
+
+## 관련 문서
+
+- [스크립트 & 코드 실행](scripting.md) — 인스턴스에 스크립트 추가/수정
+- [에셋 & 오브젝트 연출](assets-and-effects.md) — 모델 삽입, 트윈, 이펙트
+- [도구 전체 목록](overview.md)

package/docs/ko/tools/overview.md

@@ -2,6 +2,20 @@
 
 MCP 도구의 상세 파라미터는 MCP 도구 정의를 직접 확인하세요.
 
+## 기능별 가이드
+
+워크플로우 중심의 상세 가이드를 참고하세요:
+
+| 카테고리 | 설명 | 포함 도구 |
+|---------|------|----------|
+| [인스턴스 & 속성](instances-and-properties.md) | 인스턴스 검색, 생성, 수정, 태그 관리 | query_instances, mutate_instances, manage_properties |
+| [스크립트 & 코드 실행](scripting.md) | 스크립트 관리, Luau 코드 실행 | manage_scripts, execute_luau |
+| [월드 환경](world-and-environment.md) | 조명, 지형, 공간 쿼리, 카메라 | manage_lighting, manage_terrain, spatial_query, manage_camera |
+| [에셋 & 오브젝트 연출](assets-and-effects.md) | 에셋 삽입, 트윈, 애니메이션, 오디오, 이펙트 | manage_assets, manage_tween, manage_animation, manage_audio, manage_effects, manage_physics |
+| [플레이테스트 & 자동 테스트](playtest.md) | 플레이테스트 제어, 자동 테스트 실행 | system_info (play/stop/pause/resume/play_status/run_test) |
+| [동기화](../sync/overview.md) | Studio ↔ 로컬 파일 동기화 | manage_sync, workspace_state |
+| [시스템 & 디버깅](system-and-debugging.md) | 연결 확인, 로그, 선택, 배치 실행 | system_info (ping/connection/usage/...), manage_logs, manage_selection, batch_execute |
+
 관련 문서:
 - [Sync 기능 상세 가이드](../sync/overview.md)
 
@@ -248,6 +262,12 @@ Sync 정책:
 | `place_info` | Place ID, 이름, 제작자 가져오기 | Pro |
 | `services` | 모든 Roblox 서비스 나열 | Pro |
 | `studio_settings` | Studio 환경설정 가져오기 | Pro |
+| `play` | Play(F5) 또는 Run(F8) 모드로 플레이테스트 시작 | Pro |
+| `stop` | 현재 플레이테스트 중지 | Pro |
+| `pause` | Run 모드 플레이테스트 일시정지 | Pro |
+| `resume` | 일시정지된 Run 모드 플레이테스트 재개 | Pro |
+| `play_status` | 플레이테스트 상태와 가능한 action 조회 | Pro |
+| `run_test` | 임시 테스트 스크립트를 주입하고 플레이테스트 실행 후 로그와 로컬 리포트 파일 생성 | Pro |
 
 ## Batch Execute (Pro)
 

package/docs/ko/tools/playtest.md

@@ -0,0 +1,134 @@
+# 플레이테스트 & 자동 테스트
+
+> Studio 플레이테스트를 AI로 제어하고, 테스트 스크립트를 주입해 자동으로 실행/검증/리포트를 생성합니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `system_info` | Pro | play, stop, pause, resume, play_status, run_test 액션 |
+
+> `system_info`의 나머지 액션(ping, connection, usage 등)은 [시스템 & 디버깅](system-and-debugging.md)을 참고하세요.
+
+## 주요 워크플로우
+
+### 수동 플레이테스트 제어
+
+```
+"Play 모드(F5)로 게임을 시작해줘"
+"현재 플레이테스트를 멈춰줘"
+```
+
+`play` → `play_status`로 상태 확인 → `stop`으로 종료합니다.
+
+### 자동 테스트 실행 (run_test)
+
+```
+"SpawnLocation이 올바른 위치에 있는지 확인하는 테스트를 작성해서 실행해줘"
+```
+
+`run_test`는 테스트 스크립트를 주입하고 플레이테스트를 자동으로 시작/수집/정리합니다.
+
+### CI 스타일 검증
+
+```
+"NPC AI가 목표 지점까지 이동하는지 Run 모드(F8)에서 테스트하고, 실패하면 로그를 보여줘"
+```
+
+`run_test`를 `mode: "run"`으로 실행하여 서버 사이드 테스트를 진행합니다.
+
+## 플레이테스트 상태 머신
+
+```
+Edit ──play──→ Running ──stop──→ Edit
+                  │                 ↑
+                pause             stop
+                  │                 │
+                  ↓                 │
+               Paused ──resume──→ Running
+```
+
+| 상태 | 가능한 액션 |
+|------|------------|
+| `edit` | play |
+| `running` | stop, pause (Run 모드만) |
+| `paused` | resume, stop |
+
+- **Play 모드 (F5)**: 클라이언트+서버 시뮬레이션. pause/resume 불가.
+- **Run 모드 (F8)**: 서버 전용 시뮬레이션. pause/resume 가능.
+
+## run_test 파이프라인
+
+`run_test`는 다음 단계를 자동으로 오케스트레이션합니다:
+
+### 1. 준비
+- Place 정보 조회 (`place_info`)
+- 기존 로그 버퍼 초기화
+
+### 2. 스크립트 주입
+- `ServerScriptService.__MCP_TestRunner`에 래핑된 테스트 스크립트 생성
+- 래퍼가 자동으로 START/FINISHED 시그널과 에러 트레이스백을 처리
+
+### 3. 실행 및 모니터링
+- 플레이테스트 시작 (Play 또는 Run 모드)
+- 500ms 간격으로 로그 폴링
+- `[WEPPY_TEST]:FINISHED` 시그널 수신 시 완료 판정
+- 타임아웃 초과 시 자동 중단 (기본 60초, 최대 300초)
+
+### 4. 정리
+- 플레이테스트 자동 중지
+- 주입된 테스트 스크립트 삭제
+- 마지막 로그 수집
+
+### 5. 리포트 생성
+로컬 파일로 리포트와 로그를 저장합니다:
+
+```
+roblox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/
+├── test-report.md    # 결과 요약 (상태, 시간, 시그널)
+└── test-log.txt      # 전체 로그 (타임스탬프, 시퀀스, 레벨)
+```
+
+**test-report.md 예시:**
+```markdown
+# Test Report
+
+- Status: passed
+- Test Name: spawn_location_test
+- Mode: run
+- Place ID: 123456
+- Duration (ms): 1523
+- Total Logs: 12
+- Signal Count: 2
+
+## Signals
+
+- START: 2026-03-12T10:30:00.000Z
+- FINISHED: 2026-03-12T10:30:01.523Z
+```
+
+## 액션 레퍼런스
+
+| 액션 | 설명 | 파라미터 | 티어 |
+|------|------|---------|------|
+| `play` | Play(F5) 또는 Run(F8) 모드로 플레이테스트 시작 | `mode`: "play" \| "run" | Pro |
+| `stop` | 현재 플레이테스트 중지 | — | Pro |
+| `pause` | Run 모드 플레이테스트 일시정지 | — | Pro |
+| `resume` | 일시정지된 Run 모드 플레이테스트 재개 | — | Pro |
+| `play_status` | 플레이테스트 상태와 가능한 액션 조회 | — | Pro |
+| `run_test` | 테스트 스크립트 주입 → 실행 → 로그 수집 → 리포트 생성 | `script` (필수), `test_name`, `mode`, `timeout` | Pro |
+
+### run_test 파라미터
+
+| 파라미터 | 타입 | 필수 | 설명 |
+|---------|------|:----:|------|
+| `script` | string | ✅ | 실행할 Luau 테스트 코드 본문 |
+| `test_name` | string | — | 리포트에 표시할 테스트 이름 |
+| `mode` | "play" \| "run" | — | 플레이테스트 모드 (기본: "play") |
+| `timeout` | number | — | 타임아웃 초 (기본: 60, 최대: 300) |
+
+## 관련 문서
+
+- [시스템 & 디버깅](system-and-debugging.md) — system_info의 연결/상태 액션, 로그 관리
+- [스크립트 & 코드 실행](scripting.md) — 스크립트 작성 및 Luau 실행
+- [도구 전체 목록](overview.md)

package/docs/ko/tools/scripting.md

@@ -0,0 +1,66 @@
+# 스크립트 & 코드 실행
+
+> 스크립트 소스 코드를 관리하고, 임의의 Luau 코드를 Studio에서 실행합니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `manage_scripts` | 혼합 | 스크립트 생성, 읽기, 수정, 검색, 종속성 분석 |
+| `execute_luau` | Pro | Roblox Studio 샌드박스에서 임의의 Luau 코드 실행 |
+
+## 주요 워크플로우
+
+### 스크립트 수정
+
+```
+"ServerScriptService의 GameManager 스크립트에서 maxPlayers를 12에서 24로 변경해줘"
+```
+
+`manage_scripts`의 `search`로 해당 줄을 찾고, `edit_replace`로 수정합니다.
+
+### 일괄 리팩터링 (Pro)
+
+```
+"모든 스크립트에서 'OldModule'을 'NewModule'로 일괄 교체해줘"
+```
+
+`manage_scripts`의 `replace`로 여러 스크립트에서 한 번에 교체합니다.
+
+### 런타임 데이터 조회 (Pro)
+
+```
+"현재 Workspace에 있는 모든 Humanoid의 Health 평균을 계산해줘"
+```
+
+`execute_luau`로 임의 Luau 코드를 실행해 런타임 데이터를 가져옵니다.
+
+## 액션 레퍼런스
+
+### Manage Scripts (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `get_source` | 스크립트 소스 코드 가져오기 | Basic |
+| `set_source` | 스크립트 소스 코드 설정 | Basic |
+| `create` | 새 스크립트 생성 | Basic |
+| `delete` | 스크립트 삭제 | Basic |
+| `edit_replace` | 스크립트의 특정 줄 교체 | Basic |
+| `edit_insert` | 특정 위치에 줄 삽입 | Basic |
+| `edit_delete` | 특정 줄 삭제 | Basic |
+| `search` | 스크립트에서 텍스트 검색 | Basic |
+| `get_dependencies` | 스크립트 종속성 가져오기 | Basic |
+| `replace` | 여러 스크립트에서 일괄 교체 | Pro |
+
+### Execute Luau (Pro)
+
+Roblox Studio 샌드박스에서 임의의 Luau 코드를 실행합니다.
+
+- **차단된 서비스**: HttpService, DataStoreService, MessagingService
+- **접근 불가**: CoreGui, CorePackages
+
+## 관련 문서
+
+- [인스턴스 & 속성](instances-and-properties.md) — 스크립트 인스턴스 생성/이동
+- [플레이테스트 & 자동 테스트](playtest.md) — 테스트 스크립트 주입 및 실행
+- [도구 전체 목록](overview.md)

package/docs/ko/tools/system-and-debugging.md

@@ -0,0 +1,85 @@
+# 시스템 & 디버깅
+
+> 연결 상태 확인, 로그 관리, 선택 제어, 배치 실행으로 개발/디버깅 생산성을 높입니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `system_info` | 혼합 | ping, connection, usage, place_info, services, studio_settings |
+| `manage_logs` | Basic | 로그 조회, 초기화, 오류 필터링 |
+| `manage_selection` | 혼합 | 선택 가져오기/설정/모니터링 |
+| `batch_execute` | Pro | 여러 명령을 단일 배치로 실행 |
+
+> `system_info`의 플레이테스트 액션(play, stop, pause, resume, play_status, run_test)은 [플레이테스트 & 자동 테스트](playtest.md)를 참고하세요.
+
+## 주요 워크플로우
+
+### 연결 확인
+
+```
+"Studio와 연결이 잘 되어 있는지 확인해줘"
+```
+
+`system_info`의 `ping`으로 빠르게 연결을 테스트합니다.
+
+### 오류 디버깅
+
+```
+"최근 오류 로그를 보여줘"
+```
+
+`manage_logs`의 `errors`로 오류만 필터링하여 조회합니다. `get`은 `sinceSeq` 커서로 증분 조회를 지원합니다.
+
+### 일괄 작업 (Pro)
+
+```
+"Workspace의 모든 Part 색상을 빨간색으로 바꾸고, 카메라를 첫 번째 Part에 포커스해줘"
+```
+
+`batch_execute`로 여러 명령을 하나의 요청으로 묶어 실행합니다.
+
+## 액션 레퍼런스
+
+### System Info (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `ping` | 연결 테스트 | Basic |
+| `connection` | 서버/플러그인 연결 정보 가져오기 | Basic |
+| `usage` | 현재 티어 가져오기 (basic/pro) | Basic |
+| `place_info` | Place ID, 이름, 제작자 가져오기 | Pro |
+| `services` | 모든 Roblox 서비스 나열 | Pro |
+| `studio_settings` | Studio 환경설정 가져오기 | Pro |
+
+### Manage Logs (Basic)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `get` | 필터링된 로그 가져오기 (`sinceSeq` 커서 증분 조회 지원) | Basic |
+| `clear` | 로그 버퍼 초기화 | Basic |
+| `errors` | 최근 오류만 가져오기 | Basic |
+
+### Manage Selection (혼합)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `get` | 현재 선택 가져오기 | Basic |
+| `set` | 현재 선택 교체 | Basic |
+| `clear` | 선택 초기화 | Basic |
+| `cached` | 왕복 없이 캐시된 선택 가져오기 | Basic |
+| `context` | 소스와 속성을 포함한 상세 컨텍스트 가져오기 | Pro |
+| `details` | 조상/자손을 포함한 계층적 상세 정보 가져오기 | Pro |
+| `add` | 선택에 항목 추가 | Pro |
+| `remove` | 선택에서 항목 제거 | Pro |
+| `watch` | 선택 변경 모니터링 | Pro |
+
+### Batch Execute (Pro)
+
+여러 명령을 단일 배치로 실행합니다. 각 명령은 도구 이름과 인수를 지정합니다. 명령은 순차적으로 실행되며 오류 시 계속 진행 여부를 선택할 수 있습니다.
+
+## 관련 문서
+
+- [플레이테스트 & 자동 테스트](playtest.md) — system_info의 플레이테스트 액션
+- [스크립트 & 코드 실행](scripting.md) — execute_luau로 디버깅 코드 실행
+- [도구 전체 목록](overview.md)

package/docs/ko/tools/world-and-environment.md

@@ -0,0 +1,102 @@
+# 월드 환경
+
+> 조명, 지형, 공간 쿼리, 카메라를 사용해 게임 월드를 구축하고 확인합니다.
+
+## 포함된 도구
+
+| 도구 | 티어 | 설명 |
+|------|:----:|------|
+| `manage_lighting` | Pro | Lighting, Atmosphere, Sky, 시간대 설정 |
+| `manage_terrain` | Pro | 지형 생성/수정/복셀 데이터 관리 |
+| `spatial_query` | Pro | 레이캐스트, 지면 탐색, 배치 검증, 높이맵 |
+| `manage_camera` | Basic | 카메라 정보 조회, 포커스 이동, 추천 뷰 |
+
+## 주요 워크플로우
+
+### 월드 분위기 설정 (Pro)
+
+```
+"해질녘 분위기로 바꿔줘. 주황색 하늘, 안개 밀도 높이고, 시간대는 18시로 설정"
+```
+
+`manage_lighting`의 `time`으로 시간대 설정, `atmosphere`로 안개 조정, `sky`로 하늘 컬러를 변경합니다.
+
+### 지형 빌딩 (Pro)
+
+```
+"맵 중앙에 반경 200의 잔디 언덕을 만들고, 주변에 물을 채워줘"
+```
+
+`manage_terrain`의 `fill_ball`로 언덕을 생성하고, `fill_block`으로 주변 물 영역을 채웁니다.
+
+### 배치 검증 (Pro)
+
+```
+"이 건물을 놓을 수 있는 평평한 땅을 찾아줘"
+```
+
+`spatial_query`의 `find_flat`으로 적합한 위치를 찾고, `check_placement`로 충돌 여부를 확인한 뒤, `manage_camera`의 `focus_position`으로 결과를 시각적으로 확인합니다.
+
+## 액션 레퍼런스
+
+### Manage Lighting (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `lighting` | Lighting 서비스 속성 설정 | Pro |
+| `atmosphere` | Atmosphere 속성 설정 | Pro |
+| `sky` | Sky 속성 설정 | Pro |
+| `terrain_props` | Terrain 물/시각 속성 설정 | Pro |
+| `time` | 시간대 설정 | Pro |
+
+### Manage Terrain (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `fill_block` | 블록 형태의 지형 채우기 | Pro |
+| `fill_ball` | 구 형태의 지형 채우기 | Pro |
+| `fill_cylinder` | 원통 형태의 지형 채우기 | Pro |
+| `fill_wedge` | 쐐기 형태의 지형 채우기 | Pro |
+| `clear_region` | 영역의 지형 초기화 | Pro |
+| `clear_bounds` | 경계의 지형 초기화 | Pro |
+| `replace_material` | 영역의 재질 교체 | Pro |
+| `colors_get` | 재질 색상 가져오기 | Pro |
+| `colors_set` | 재질 색상 설정 | Pro |
+| `read_voxel` | 단일 복셀 데이터 읽기 | Pro |
+| `read_voxels` | 대량 복셀 데이터 읽기 | Pro |
+| `write_voxels` | 대량 복셀 데이터 쓰기 | Pro |
+| `generate` | 절차적 지형 생성 | Pro |
+| `smooth` | 지형 부드럽게 하기 | Pro |
+
+### Spatial Query (Pro)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `raycast` | 단일 광선 투사 | Pro |
+| `find_ground` | 지점 아래 지면 위치 찾기 | Pro |
+| `check_placement` | 배치가 충돌 없는지 확인 | Pro |
+| `multi_raycast` | 여러 광선 일괄 투사 | Pro |
+| `scan_area` | 영역의 높이맵 생성 | Pro |
+| `find_flat` | 건축을 위한 평평한 영역 찾기 | Pro |
+| `find_spawn` | 적절한 스폰 위치 찾기 | Pro |
+| `analyze_walkable` | 이동 가능 영역 그리드 분석 | Pro |
+| `spatial_map` | 모든 BasePart 위치 가져오기 | Pro |
+| `find_space` | 오브젝트를 위한 빈 공간 찾기 | Pro |
+| `bounds` | 인스턴스의 바운딩 박스 가져오기 | Pro |
+| `snap_grid` | 위치를 그리드에 스냅 | Pro |
+| `collision` | AABB 충돌 확인 | Pro |
+
+### Manage Camera (Basic)
+
+| 액션 | 설명 | 티어 |
+|------|------|------|
+| `info` | 카메라 위치, 회전, FOV, 뷰포트 크기 가져오기 | Basic |
+| `focus_path` | 카메라를 인스턴스에 포커스 이동 | Basic |
+| `focus_position` | 카메라를 위치에 포커스 이동 | Basic |
+| `suggest` | 대상에 대한 추천 카메라 뷰 가져오기 | Basic |
+
+## 관련 문서
+
+- [인스턴스 & 속성](instances-and-properties.md) — 월드 오브젝트 배치
+- [에셋 & 오브젝트 연출](assets-and-effects.md) — 이펙트, 트윈, 오디오
+- [도구 전체 목록](overview.md)