@weppy/roblox-mcp 1.4.2 → 1.5.1

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)

package/docs/pt-br/README.md

@@ -56,7 +56,15 @@ A IA trabalha com um espelho local sincronizado, entao alteracoes em varios arqu
 - Basic: sincronizacao unidirecional (Studio -> Local)
 - Pro: sincronizacao bidirecional + Direction/Apply Mode por tipo + historico + multiplace
 
-### 3) Roblox Explorer: navegue a hierarquia do Studio no VSCode
+### 3) Playtest: a IA executa e valida testes automaticamente
+
+A IA pode controlar diretamente o playtest do Studio. Ela pode iniciar e parar Play (F5) ou Run (F8), injetar scripts de teste, coletar logs e gerar relatorios locais automaticamente.
+
+- "Inicie um playtest em modo Run e verifique se o NPC chega ao objetivo."
+- "Escreva e execute um teste para confirmar que o SpawnLocation esta acima do chao."
+- "Valide com playtest se o script que acabei de alterar roda sem erros."
+
+### 4) Roblox Explorer: navegue a hierarquia do Studio no VSCode
 
 Visualize a arvore completa de instancias do seu lugar no Roblox Studio diretamente dentro do VSCode. Navegue pelos servicos, abra scripts e arquivos de propriedades sincronizados, e acompanhe o status de sincronizacao — tudo sem trocar para o Studio.
 
@@ -76,12 +84,21 @@ Visualize a arvore completa de instancias do seu lugar no Roblox Studio diretame
 ## Documentacao detalhada
 
 - [Guia de instalacao](../en/installation/README.md)
-- [Cobertura de ferramentas](../en/tools/overview.md)
-- [Guia detalhado de Sync](../en/sync/overview.md)
+- [Lista completa de tools](tools/overview.md)
+- [Guia detalhado de Sync](sync/overview.md)
 - [Roblox Explorer (Extensao VSCode)](../en/installation/roblox-explorer.md)
 - [Compatibilidade](../compatibility.md)
 - [Solucao de problemas](../troubleshooting.md)
 
+### Guias por fluxo
+
+- [Instancias e propriedades](tools/instances-and-properties.md) - busca, criacao, edicao e tags
+- [Scripts e execucao de codigo](tools/scripting.md) - gerenciamento de scripts e execucao de Luau
+- [Mundo e ambiente](tools/world-and-environment.md) - iluminacao, terrain e camera
+- [Assets e efeitos](tools/assets-and-effects.md) - insercao de modelos, tween e efeitos
+- [Playtest e testes automatizados](tools/playtest.md) - controle de playtest e validacao automatica
+- [Sistema e depuracao](tools/system-and-debugging.md) - conexao, logs e execucao em lote
+
 ## Upgrade Pro
 
 Sync bidirecional, recursos avancados de criacao e eficiencia de tokens de IA — tudo em uma unica atualizacao.

package/docs/pt-br/pro-upgrade.md

@@ -53,5 +53,6 @@ Geração de terrain, busca de assets, análise espacial, animação, áudio e a
 | Resync / Reconstruir estado | ❌ | ✅ |
 | Histórico de mudanças | ❌ | ✅ |
 | Sync multi-place | ❌ | ✅ Até 3 places com armazenamento isolado |
+| Controle de Playtest (Reproduzir/Parar/Pausar/Retomar) | ❌ | ✅ |
 | Cobertura avançada de tools | Conjunto base | Conjunto avançado mais amplo |
 | Eficiência de tokens IA | Padrão | Melhor com ações em massa / de alto impacto |

package/docs/pt-br/tools/assets-and-effects.md

@@ -0,0 +1,104 @@
+# Assets e efeitos
+
+> Insira assets e controle tween, audio, particulas, animacao e grupos de colisao.
+
+## Tools incluidas
+
+| Tool | Tier | Descricao |
+|------|:----:|-----------|
+| `manage_assets` | Pro | Busca na Creator Store, insere modelos e pacotes, consulta info do asset |
+| `manage_tween` | Pro | Cria, reproduz, pausa e cancela tweens |
+| `manage_animation` | Pro | Carrega, reproduz, para e inspeciona tracks de animacao |
+| `manage_audio` | Pro | Reproduz, para, pausa e retoma sons; configura o listener |
+| `manage_effects` | Pro | Emite particulas, limpa efeitos e alterna seu estado |
+| `manage_physics` | Pro | Registra grupos de colisao e configura colisoes |
+
+## Fluxos principais
+
+### Montar uma cena com assets
+
+```
+"Busque um modelo de arvore na Creator Store e coloque tres no Workspace."
+```
+
+Use `manage_assets.search_insert` para buscar e inserir em um unico passo.
+
+### Criar uma interacao visual
+
+```
+"Faca a porta abrir com um tween de 3 segundos quando for clicada."
+```
+
+Use `manage_tween.create` para definir o movimento e `manage_tween.play` para reproduzi-lo. Voce pode combinar com `manage_audio.play` para o som.
+
+### Combinar particulas e audio
+
+```
+"Reproduza um som de explosao e emita particulas quando o boss aparecer."
+```
+
+Use `manage_effects.emit` para as particulas e `manage_audio.play` para o som.
+
+## Referencia de acoes
+
+### Manage Assets (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `insert` | Inserir um modelo por ID de asset | Pro |
+| `info` | Obter metadados do asset | Pro |
+| `search` | Buscar na Creator Store | Pro |
+| `search_insert` | Buscar e inserir a primeira correspondencia | Pro |
+| `insert_free` | Inserir um modelo gratuito | Pro |
+| `insert_package` | Inserir um pacote | Pro |
+| `export` | Exportar a selecao atual | Pro |
+
+### Manage Tween (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `create` | Criar um tween com propriedades alvo | Pro |
+| `play` | Reproduzir um tween criado | Pro |
+| `pause` | Pausar um tween em execucao | Pro |
+| `cancel` | Cancelar um tween | Pro |
+
+### Manage Animation (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `load` | Carregar uma animacao em Humanoid ou AnimationController | Pro |
+| `play` | Reproduzir um track de animacao carregado | Pro |
+| `stop` | Parar uma animacao em reproducao | Pro |
+| `get_tracks` | Listar todos os tracks de animacao carregados | Pro |
+
+### Manage Audio (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `play` | Reproduzir um som e criar `Sound` se necessario | Pro |
+| `stop` | Parar um som em reproducao | Pro |
+| `pause` | Pausar um som em reproducao | Pro |
+| `resume` | Retomar um som pausado | Pro |
+| `set_listener` | Definir o tipo ou alvo do listener de audio | Pro |
+
+### Manage Effects (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `emit` | Emitir particulas a partir de `ParticleEmitter` | Pro |
+| `clear` | Limpar todas as particulas | Pro |
+| `toggle` | Ativar ou desativar um efeito | Pro |
+
+### Manage Physics (Pro)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `register_group` | Registrar um grupo de colisao | Pro |
+| `set_collidable` | Definir se dois grupos podem colidir | Pro |
+| `get_groups` | Listar todos os grupos de colisao registrados | Pro |
+
+## Documentos relacionados
+
+- [Instancias e propriedades](instances-and-properties.md) - criar e posicionar objetos
+- [Mundo e ambiente](world-and-environment.md) - iluminacao, terrain e camera
+- [Lista completa de tools](overview.md)

package/docs/pt-br/tools/instances-and-properties.md

@@ -0,0 +1,104 @@
+# Instancias e propriedades
+
+> Busque, crie e edite instancias do Roblox Studio enquanto gerencia propriedades, atributos e tags.
+
+## Tools incluidas
+
+| Tool | Tier | Descricao |
+|------|:----:|-----------|
+| `query_instances` | Misto | Busca instancias, percorre a hierarquia e inspeciona informacoes de classe |
+| `mutate_instances` | Misto | Cria, exclui, clona, move e renomeia instancias |
+| `manage_properties` | Misto | Le e escreve propriedades, atributos e tags |
+
+## Fluxos principais
+
+### Entender a estrutura da cena
+
+```
+"Procure todos os Part dentro de Workspace e me diga a posicao e o tamanho."
+```
+
+Use `query_instances.search_class` para encontrar os Part e `manage_properties.mass_get` para ler `Position` e `Size` em lote.
+
+### Posicionar objetos em lote
+
+```
+"Coloque 4 SpawnLocation em um quadrado no centro do mapa e defina um TeamColor diferente para cada um."
+```
+
+Use `mutate_instances.mass_create` para criar tudo em uma solicitacao e `manage_properties.mass_set` para definir as propriedades.
+
+### Gerenciar por tag
+
+```
+"Encontre todos os objetos com a tag Collectible e mude Anchored para true."
+```
+
+Use `manage_properties.get_tagged` para reunir as instancias e `manage_properties.mass_set` para atualiza-las.
+
+## Referencia de acoes
+
+### Query Instances (Misto)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `get` | Obter propriedades da instancia por caminho | Basic |
+| `children` | Obter filhos imediatos ou todos os descendentes | Basic |
+| `find_child` | Buscar o primeiro filho por nome e filtro opcional de classe | Basic |
+| `find_descendant` | Buscar o primeiro descendente por nome | Basic |
+| `wait_for_child` | Esperar um filho aparecer (com timeout) | Basic |
+| `class_info` | Obter informacoes de classe e propriedades validas | Basic |
+| `search_name` | Buscar instancias por padrao de nome (com curingas) | Basic |
+| `search_class` | Buscar instancias por nome de classe | Basic |
+| `file_tree` | Obter estrutura de arvore de arquivos a partir da raiz | Pro |
+| `project_structure` | Obter estrutura completa do projeto | Pro |
+| `descendants` | Obter todos os descendentes de uma instancia | Pro |
+| `ancestors` | Obter todos os ancestrais de uma instancia | Pro |
+| `search_property` | Buscar instancias por valor de propriedade | Pro |
+| `search_tag` | Buscar instancias por tag | Pro |
+
+### Mutate Instances (Misto)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `create` | Criar uma nova instancia | Basic |
+| `create_with_props` | Criar instancia com propriedades iniciais | Basic |
+| `delete` | Excluir uma instancia | Basic |
+| `clone` | Clonar uma instancia | Basic |
+| `move` | Mover instancia para um novo pai | Basic |
+| `rename` | Renomear uma instancia | Basic |
+| `pivot` | Definir posicao de pivot ou CFrame | Basic |
+| `create_tree` | Criar uma arvore hierarquica de instancias | Pro |
+| `mass_create` | Criar varias instancias de uma vez | Pro |
+| `mass_delete` | Excluir varias instancias | Pro |
+| `mass_duplicate` | Duplicar varias instancias | Pro |
+| `smart_duplicate` | Duplicar com espacamento e quantidade | Pro |
+
+### Manage Properties (Misto)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `get` | Obter o valor de uma propriedade | Basic |
+| `set` | Definir o valor de uma propriedade | Basic |
+| `get_all` | Obter todas as propriedades de uma instancia | Basic |
+| `set_multiple` | Definir varias propriedades de uma vez | Basic |
+| `get_attr` | Obter o valor de um atributo | Basic |
+| `set_attr` | Definir o valor de um atributo | Basic |
+| `get_all_attrs` | Obter todos os atributos | Basic |
+| `delete_attr` | Excluir um atributo | Basic |
+| `add_tag` | Adicionar uma tag a uma instancia | Basic |
+| `remove_tag` | Remover uma tag de uma instancia | Basic |
+| `check_tag` | Verificar se uma instancia possui uma tag | Basic |
+| `get_tags` | Obter todas as tags de uma instancia | Basic |
+| `get_tagged` | Obter todas as instancias com uma tag especifica | Basic |
+| `set_calculated` | Definir uma propriedade usando expressao matematica | Pro |
+| `set_relative` | Definir uma propriedade relativa ao valor atual | Pro |
+| `mass_set` | Definir uma propriedade em varias instancias | Pro |
+| `mass_get` | Obter uma propriedade de varias instancias | Pro |
+| `modify_children` | Modificar todos os filhos de um pai | Pro |
+
+## Documentos relacionados
+
+- [Scripts e execucao de codigo](scripting.md) - adicionar ou editar scripts em instancias
+- [Assets e efeitos](assets-and-effects.md) - inserir modelos, tween e efeitos
+- [Lista completa de tools](overview.md)

package/docs/pt-br/tools/overview.md

@@ -2,6 +2,20 @@
 
 Para parametros detalhados, consulte as definicoes de ferramentas MCP diretamente.
 
+## Guias por fluxo
+
+Consulte estes guias orientados a fluxo de trabalho:
+
+| Categoria | Descricao | Tools incluidas |
+|-----------|-----------|-----------------|
+| [Instancias e propriedades](instances-and-properties.md) | Busca, criacao, edicao e tags de instancias | `query_instances`, `mutate_instances`, `manage_properties` |
+| [Scripts e execucao de codigo](scripting.md) | Gerenciamento de scripts e execucao de Luau | `manage_scripts`, `execute_luau` |
+| [Mundo e ambiente](world-and-environment.md) | Iluminacao, terrain, consultas espaciais e camera | `manage_lighting`, `manage_terrain`, `spatial_query`, `manage_camera` |
+| [Assets e efeitos](assets-and-effects.md) | Insercao de assets, tween, animacao, audio e efeitos | `manage_assets`, `manage_tween`, `manage_animation`, `manage_audio`, `manage_effects`, `manage_physics` |
+| [Playtest e testes automatizados](playtest.md) | Controle de playtest e validacao automatica | `system_info` (`play`, `stop`, `pause`, `resume`, `play_status`, `run_test`) |
+| [Sync](../sync/overview.md) | Sincronizacao entre Studio e arquivos locais | `manage_sync`, `workspace_state` |
+| [Sistema e depuracao](system-and-debugging.md) | Conexao, logs, selecao e execucao em lote | `system_info` (`ping`, `connection`, `usage`, ...), `manage_logs`, `manage_selection`, `batch_execute` |
+
 Documentacao relacionada:
 - [Guia detalhado de Sync](../sync/overview.md)
 
@@ -248,6 +262,12 @@ Politica de Sync:
 | `place_info` | Obter Place ID, nome, criador | Pro |
 | `services` | Listar todos os servicos Roblox | Pro |
 | `studio_settings` | Obter preferencias do Studio | Pro |
+| `play` | Iniciar playtest em modo Play (F5) ou Run (F8) | Pro |
+| `stop` | Parar o playtest ativo | Pro |
+| `pause` | Pausar o playtest ativo em modo Run | Pro |
+| `resume` | Retomar o playtest pausado em modo Run | Pro |
+| `play_status` | Obter estado do playtest e acoes disponiveis | Pro |
+| `run_test` | Injetar um script temporario de teste, executar o playtest, coletar logs e gerar relatorios locais | Pro |
 
 ## Batch Execute (Pro)
 

package/docs/pt-br/tools/playtest.md

@@ -0,0 +1,140 @@
+# Playtest e testes automatizados
+
+> Controle o playtest do Roblox Studio com IA, injete scripts de teste e gere logs e relatorios locais automaticamente.
+
+## Tools incluidas
+
+| Tool | Tier | Descricao |
+|------|:----:|-----------|
+| `system_info` | Pro | acoes `play`, `stop`, `pause`, `resume`, `play_status`, `run_test` |
+
+> Para outras acoes de `system_info` como `ping`, `connection` e `usage`, consulte [Sistema e depuracao](system-and-debugging.md).
+
+## Fluxos principais
+
+### Controle manual de playtest
+
+```
+"Inicie o jogo em modo Play (F5)."
+"Pare o playtest atual."
+```
+
+Fluxo tipico: `play` -> `play_status` -> `stop`.
+
+### Executar um teste automatizado
+
+```
+"Escreva e execute um teste que verifique se o SpawnLocation esta posicionado corretamente."
+```
+
+`run_test` injeta o script de teste, inicia o playtest automaticamente, coleta logs e faz a limpeza.
+
+### Validacao estilo CI
+
+```
+"Execute um teste em modo Run (F8) que verifique se o NPC chega ao objetivo e me mostre os logs se falhar."
+```
+
+Use `run_test` com `mode: "run"` para validacoes focadas no servidor.
+
+## Maquina de estados do playtest
+
+```text
+Edit --play--> Running --stop--> Edit
+                  |               ^
+                pause             |
+                  |               |
+                  v               |
+               Paused --resume--> Running
+```
+
+| Estado | Acoes disponiveis |
+|--------|-------------------|
+| `edit` | `play` |
+| `running` | `stop`, `pause` (apenas modo Run) |
+| `paused` | `resume`, `stop` |
+
+- Modo Play (F5): simulacao de cliente + servidor, sem pausa ou retomada
+- Modo Run (F8): simulacao apenas de servidor, com pausa e retomada
+
+## Fluxo de `run_test`
+
+`run_test` orquestra estas etapas automaticamente:
+
+### 1. Preparacao
+
+- Ler informacoes do place com `place_info`
+- Limpar o buffer de logs existente
+
+### 2. Injecao do script
+
+- Criar `ServerScriptService.__MCP_TestRunner` com um script de teste encapsulado
+- O wrapper cuida dos sinais `START` e `FINISHED` e dos tracebacks de erro
+
+### 3. Execucao e monitoramento
+
+- Iniciar o playtest em modo Play ou Run
+- Consultar logs a cada 500 ms
+- Finalizar quando `[WEPPY_TEST]:FINISHED` for detectado
+- Parar automaticamente ao atingir timeout (60 segundos por padrao, 300 no maximo)
+
+### 4. Limpeza
+
+- Parar o playtest automaticamente
+- Excluir o script de teste injetado
+- Coletar os logs finais
+
+### 5. Escrita de relatorios
+
+Os relatorios e logs sao gravados em arquivos locais:
+
+```text
+roblox-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/
+├── test-report.md
+└── test-log.txt
+```
+
+Exemplo de `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
+```
+
+## Referencia de acoes
+
+| Acao | Descricao | Parametros | Tier |
+|------|-----------|------------|------|
+| `play` | Iniciar playtest em modo Play (F5) ou Run (F8) | `mode`: `"play"` \| `"run"` | Pro |
+| `stop` | Parar o playtest atual | - | Pro |
+| `pause` | Pausar um playtest em modo Run | - | Pro |
+| `resume` | Retomar um playtest pausado em modo Run | - | Pro |
+| `play_status` | Obter o estado do playtest e as acoes disponiveis | - | Pro |
+| `run_test` | Injetar script de teste, executar playtest, coletar logs e escrever relatorios | `script` (obrigatorio), `test_name`, `mode`, `timeout` | Pro |
+
+### Parametros de `run_test`
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|:-----------:|-----------|
+| `script` | string | ✅ | Corpo do codigo Luau de teste a executar |
+| `test_name` | string | - | Nome exibido no relatorio |
+| `mode` | `"play"` \| `"run"` | - | Modo de playtest, padrao `"play"` |
+| `timeout` | number | - | Timeout em segundos, padrao 60, maximo 300 |
+
+## Documentos relacionados
+
+- [Sistema e depuracao](system-and-debugging.md) - acoes de conexao e gerenciamento de logs
+- [Scripts e execucao de codigo](scripting.md) - escrever scripts e executar Luau
+- [Lista completa de tools](overview.md)

package/docs/pt-br/tools/scripting.md

@@ -0,0 +1,66 @@
+# Scripts e execucao de codigo
+
+> Gerencie o codigo-fonte de scripts e execute Luau arbitrario dentro do Roblox Studio.
+
+## Tools incluidas
+
+| Tool | Tier | Descricao |
+|------|:----:|-----------|
+| `manage_scripts` | Misto | Criar, ler, editar, buscar e analisar dependencias de scripts |
+| `execute_luau` | Pro | Executar Luau arbitrario no sandbox do Roblox Studio |
+
+## Fluxos principais
+
+### Editar um script
+
+```
+"Altere maxPlayers de 12 para 24 no script GameManager dentro de ServerScriptService."
+```
+
+Use `manage_scripts.search` para encontrar a linha correta e `manage_scripts.edit_replace` para atualiza-la.
+
+### Refatorar varios scripts (Pro)
+
+```
+"Substitua OldModule por NewModule em todos os scripts."
+```
+
+Use `manage_scripts.replace` para aplicar a mudanca em varios scripts em uma solicitacao.
+
+### Inspecionar dados de runtime (Pro)
+
+```
+"Calcule a media de Health de todos os Humanoid que estao em Workspace."
+```
+
+Use `execute_luau` para rodar Luau personalizado e ler dados do runtime atual.
+
+## Referencia de acoes
+
+### Manage Scripts (Misto)
+
+| Acao | Descricao | Tier |
+|------|-----------|------|
+| `get_source` | Obter codigo-fonte do script | Basic |
+| `set_source` | Definir codigo-fonte do script | Basic |
+| `create` | Criar um novo script | Basic |
+| `delete` | Excluir um script | Basic |
+| `edit_replace` | Substituir linhas especificas em um script | Basic |
+| `edit_insert` | Inserir linhas em uma posicao | Basic |
+| `edit_delete` | Excluir linhas especificas | Basic |
+| `search` | Buscar texto em scripts | Basic |
+| `get_dependencies` | Obter dependencias de um script | Basic |
+| `replace` | Substituicao em massa em scripts | Pro |
+
+### Execute Luau (Pro)
+
+Executa Luau arbitrario dentro do sandbox do Roblox Studio.
+
+- Servicos bloqueados: `HttpService`, `DataStoreService`, `MessagingService`
+- APIs inacessiveis: `CoreGui`, `CorePackages`
+
+## Documentos relacionados
+
+- [Instancias e propriedades](instances-and-properties.md) - criar ou mover instancias de script
+- [Playtest e testes automatizados](playtest.md) - injetar e executar scripts de teste
+- [Lista completa de tools](overview.md)