O que s&box CLI faz?
CLI nativo para agentes do motor de jogos s&box (Facepunch Studios, Source 2). Mais de 79 comandos em 14 grupos. Manipule arquivos .scene, .prefab, .vmat, .sound, Input.config, Collision.config JSON diretamente, gere componentes C# idiomáticos e execute um grafo de assets em tempo real no projeto.
Instalação
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=sbox/agent-harness
Requisitos
- Python 3.10+
- s&box instalado via Steam — detectado automaticamente, ou defina
SBOX_PATHpara um diretório de instalação personalizado. - A maioria dos comandos funciona inteiramente nos arquivos JSON do projeto — o s&box não precisa estar em execução.
Opções Globais
--json Saída JSON legível por máquina (sempre passe para uso por agente)
--project PATH Diretório do projeto (detectado automaticamente a partir do cwd com .sbproj se omitido)
Grupos de Comandos
project — Gerenciar projetos s&box
cli-anything-sbox project new --name MeuJogo --output-dir ./MeuJogo
cli-anything-sbox --json project info
cli-anything-sbox project config --max-players 32 --tick-rate 64
cli-anything-sbox --json --project ./MeuJogo project add-package facepunch.libsdf
cli-anything-sbox --json --project ./MeuJogo project remove-package facepunch.libsdf
# Lint: referências de asset quebradas, GUIDs duplicados, Input.config malformado
cli-anything-sbox --json --project ./MeuJogo project validate
cli-anything-sbox --project ./MeuJogo project validate --no-inputs --no-guids
scene — Manipular arquivos .scene
cli-anything-sbox scene new --name gameplay -o ./Assets/scenes/gameplay.scene
cli-anything-sbox --json scene info ./scene.scene
cli-anything-sbox --json scene list ./scene.scene
cli-anything-sbox scene add-object ./scene.scene Inimigo --position "100,0,0" --components "model,box_collider,rigidbody" --tags "inimigo"
cli-anything-sbox scene remove-object ./scene.scene --name Inimigo
cli-anything-sbox scene add-component ./scene.scene <guid-do-objeto> Sandbox.PointLight
cli-anything-sbox scene remove-component ./scene.scene <guid-do-objeto> --component-type Sandbox.Rigidbody
cli-anything-sbox --json scene modify-object ./scene.scene --guid <guid> --name NovoNome --position "200,0,0"
cli-anything-sbox --json scene clone-object ./scene.scene --name Inimigo --new-name CopiaInimigo --position "300,0,0"
cli-anything-sbox --json scene get-object ./scene.scene --name Sol
cli-anything-sbox scene set-property ./scene.scene --fixed-update-freq 64 --timescale 0.5
cli-anything-sbox scene set-navmesh ./scene.scene --enabled --agent-height 72 --agent-radius 16
cli-anything-sbox --json scene list-presets
cli-anything-sbox --json scene modify-component ./scene.scene <guid-do-objeto> <guid-do-componente> --properties '{"Damage":50}'
# Encontrar objetos correspondentes a um ou mais filtros (combinados com AND)
cli-anything-sbox --json scene query ./scene.scene --has-component rigidbody --has-tag torre
cli-anything-sbox --json scene query ./scene.scene --name-regex "^Torre\d$" --in-bounds "0,-500,-50,1000,500,50"
# Extrair toda referência de asset (.vmdl, .vmat, .vsnd, .vtex, .vpcf, .prefab) de uma cena
cli-anything-sbox --json scene refs ./scene.scene
# Aplicar a mesma modificação em cada objeto que corresponder a uma consulta
cli-anything-sbox --json scene bulk-modify ./scene.scene --has-tag torre --position "0,0,100" --enable
# Diff estrutural entre duas cenas (GameObjects adicionados/removidos/modificados + SceneProperties)
cli-anything-sbox --json scene diff ./old.scene ./new.scene
# Inserir um prefab como GameObject em uma cena
cli-anything-sbox --json scene instantiate-prefab ./level.scene ./Assets/prefabs/bullet.prefab --position "10,0,0"
prefab — Gerenciar arquivos .prefab
cli-anything-sbox prefab new --name Bala -o ./Assets/prefabs/bala.prefab --components "model,sphere_collider,rigidbody"
cli-anything-sbox --json prefab info ./Assets/prefabs/bala.prefab
cli-anything-sbox prefab from-scene ./scene.scene <guid-do-objeto> -o ./Assets/prefabs/extraido.prefab
cli-anything-sbox --json prefab add-component ./prefab.prefab rigidbody
cli-anything-sbox prefab remove-component ./prefab.prefab --component-type Sandbox.Rigidbody
cli-anything-sbox --json prefab list
# Referências de asset dentro de um prefab
cli-anything-sbox --json prefab refs ./prefab.prefab
# Modificar propriedades de componentes em um prefab (por tipo de componente ou GUID do componente)
cli-anything-sbox --json prefab modify-component ./prefab.prefab --component-type Sandbox.Rigidbody --properties '{"Gravity":false,"MassOverride":50}'
# Diff estrutural entre dois prefabs (raiz + filhos nomeados)
cli-anything-sbox --json prefab diff ./old.prefab ./new.prefab
codegen — Gerar código C#
# Componente simples
cli-anything-sbox codegen component --name PlayerController --methods OnUpdate,OnFixedUpdate -o ./Code/PlayerController.cs
# Componente com campos [Property]
cli-anything-sbox --json codegen component --name Torre --properties '[{"name":"Damage","type":"float","default":"25f"},{"name":"Range","type":"float","default":"500f"}]'
# Componente de rede (classe parcial) com stubs de métodos RPC
cli-anything-sbox codegen component --name NetPlayer --networked --methods OnUpdate,OnFixedUpdate --rpc-methods "Fire:Broadcast,TakeDamage:Host" -o ./Code/NetPlayer.cs
# GameResource
cli-anything-sbox codegen gameresource --name TowerData --display-name "Dados da Torre" --extension torre -o ./Code/TowerData.cs
# Menu do editor (assembly Editor/)
cli-anything-sbox codegen editor-menu --name MyTools --menu-path "Editor/My Tools/Open" -o ./Editor/MyTools.cs
# Componente UI Razor simples (.razor + .razor.scss)
cli-anything-sbox codegen razor --name HudPanel --properties '[{"name":"Score","type":"int","default":"0"}]' -o ./UI/HudPanel.razor
# Classe estática ou derivada de base
cli-anything-sbox codegen class --name Math2 --static -o ./Code/Math2.cs
# PanelComponent + ScreenPanel irmão (lida com a peculiaridade do s&box onde
# a entrada do PanelComponent só funciona quando ambos estão no mesmo GameObject).
# Emite .razor + .razor.scss + um snippet de GameObject pronto para colar, ou anexa
# diretamente a uma cena com --scene.
cli-anything-sbox --json codegen panel-component --name HudBar -o ./UI/HudBar.razor
cli-anything-sbox codegen panel-component --name Crosshair -o ./UI/Crosshair.razor --scene ./Assets/scenes/game.scene
input — Gerenciar Input.config
cli-anything-sbox --json input list
cli-anything-sbox input add --name PlaceTower --group Gameplay --keyboard mouse1 --gamepad RightTrigger
cli-anything-sbox input remove --name PlaceTower
cli-anything-sbox input set --name Attack1 --keyboard mouse1
collision — Gerenciar Collision.config
cli-anything-sbox --json collision list
cli-anything-sbox collision add-layer --name projetil --default Collide
cli-anything-sbox collision add-rule --layer-a projetil --layer-b solido --result Collide
cli-anything-sbox collision remove-rule --layer-a projetil --layer-b solido
cli-anything-sbox collision remove-layer --name projetil
material — Gerenciar materiais .vmat
cli-anything-sbox --json material new --name chao --shader complex --color-texture "textures/chao.tga" --metalness 0.3 -o ./Assets/materials/chao.vmat
cli-anything-sbox --json material info ./Assets/materials/chao.vmat
cli-anything-sbox --json material list
cli-anything-sbox --json material set ./Assets/materials/chao.vmat --metalness 0.8
sound — Gerenciar eventos .sound
cli-anything-sbox --json sound new --name tiro --sounds "sounds/tiro1.vsnd,sounds/tiro2.vsnd" --volume 0.8 -o ./Assets/sounds/tiro.sound
cli-anything-sbox --json sound info ./Assets/sounds/tiro.sound
cli-anything-sbox --json sound list
cli-anything-sbox --json sound set ./Assets/sounds/tiro.sound --volume 0.5
localization — Gerenciar traduções
cli-anything-sbox localization new --lang pt -o ./Localization/pt.json
cli-anything-sbox localization set ./Localization/pt.json --key "game.title" --value "Meu Jogo"
cli-anything-sbox --json localization list ./Localization/pt.json
cli-anything-sbox localization get ./Localization/pt.json --key "game.title"
cli-anything-sbox localization remove ./Localization/pt.json --key "game.title"
cli-anything-sbox localization bulk-set ./Localization/pt.json --keys '{"ui.start":"Iniciar","ui.quit":"Sair"}'
server — Servidor dedicado
cli-anything-sbox server info
cli-anything-sbox server start --game meu_jogo --map facepunch.flatgrass
asset — Gerenciamento de assets e buscas reversas
cli-anything-sbox --json asset list --type scene
cli-anything-sbox --json asset info ./Assets/scenes/minimal.scene
cli-anything-sbox asset compile ./Assets/materials/chao.vmat
# Quais cenas/prefabs referenciam este asset?
cli-anything-sbox --json --project ./MeuJogo asset find-refs models/meutime/widget.vmdl
# Encontrar assets não referenciados (por tipo, ou em todos os tipos referenciáveis)
cli-anything-sbox --json --project ./MeuJogo asset find-unused
cli-anything-sbox --json --project ./MeuJogo asset find-unused --type model --type material
# Renomear um asset e atualizar todas as referências em cenas/prefabs (extensão preservada se omitida)
cli-anything-sbox --json --project ./MeuJogo asset rename models/time/widget.vmdl gizmo
cli-anything-sbox --project ./MeuJogo asset rename models/time/widget.vmdl gizmo --dry-run
# Mover um asset entre diretórios e atualizar todas as referências
cli-anything-sbox --json --project ./MeuJogo asset move models/time/widget.vmdl models/compartilhado/widget.vmdl
session — Gerenciamento de estado
cli-anything-sbox session status
cli-anything-sbox session undo
cli-anything-sbox session redo
test — Harness automatizado de geração de mapa/cena
cli-anything-sbox test setup
cli-anything-sbox --json test run
launch — Abrir projeto no editor do s&box
cli-anything-sbox launch
Presets de Componentes
29 nomes curtos utilizáveis com --components em scene add-object, prefab new, etc. Cada um mapeia para um tipo de componente Sandbox.*.
| Preset | Tipo de Componente |
|---|---|
model | Sandbox.ModelRenderer |
box_collider | Sandbox.BoxCollider |
sphere_collider | Sandbox.SphereCollider |
capsule_collider | Sandbox.CapsuleCollider |
plane_collider | Sandbox.PlaneCollider |
model_collider | Sandbox.ModelCollider |
rigidbody | Sandbox.Rigidbody |
character_controller | Sandbox.CharacterController |
player_controller | Sandbox.PlayerController |
camera | Sandbox.CameraComponent |
light_directional | Sandbox.DirectionalLight |
light_point | Sandbox.PointLight |
spot_light | Sandbox.SpotLight |
ambient_light | Sandbox.AmbientLight |
sprite_renderer | Sandbox.SpriteRenderer |
skinned_model_renderer | Sandbox.SkinnedModelRenderer |
text_renderer | Sandbox.TextRenderer |
line_renderer | Sandbox.LineRenderer |
decal_renderer | Sandbox.DecalRenderer |
trail_renderer | Sandbox.TrailRenderer |
particle_effect | Sandbox.ParticleEffect |
sound_point | Sandbox.SoundPointComponent |
nav_mesh_agent | Sandbox.NavMeshAgent |
screen_panel | Sandbox.ScreenPanel |
world_panel | Sandbox.WorldPanel |
fixed_joint | Sandbox.FixedJoint |
hinge_joint | Sandbox.HingeJoint |
spring_joint | Sandbox.SpringJoint |
ball_socket_joint | Sandbox.BallSocketJoint |
scene list-presets retorna o registro de presets ativo como JSON.
Padrão de Uso para Agentes
Passe --json em toda invocação conduzida por agente. Use jq para encadear GUIDs e caminhos entre comandos:
# Inicializar um projeto
sbproj=$(cli-anything-sbox --json project new --name MeuJogo --output-dir /tmp/MeuJogo | jq -r '.sbproj')
cd /tmp/MeuJogo
# Adicionar uma torre com uma configuração específica de componentes, capturar seu GUID
guid=$(cli-anything-sbox --json scene add-object ./Assets/scenes/main.scene Torre \
--components "model,box_collider,rigidbody" --tags "torre" \
| jq -r '.guid')
# Gerar o componente C# correspondente, com rede
cli-anything-sbox --json codegen component --name Torre --networked \
--rpc-methods "Fire:Host" --properties '[{"name":"Damage","type":"float","default":"25f"}]' \
-o ./Code/Torre.cs
# Ajustar em massa toda torre na cena
cli-anything-sbox --json scene bulk-modify ./Assets/scenes/main.scene \
--has-tag torre --enable --position-y-add 50
# Validar antes de confirmar
cli-anything-sbox --json project validate
Modo REPL
cli-anything-sbox sem argumentos entra em um REPL interativo com um prompt estilizado:
$ cli-anything-sbox
cli-anything-sbox> project info
cli-anything-sbox> scene list ./Assets/scenes/main.scene
cli-anything-sbox> codegen component --name Foo -o ./Code/Foo.cs
cli-anything-sbox> quit
Variáveis de Ambiente
| Variável | Descrição | Padrão |
|---|---|---|
SBOX_PATH | Diretório de instalação do s&box | Detectado automaticamente nas pastas da biblioteca Steam |
CLI_ANYTHING_SKILL_REPO | Sobrescreve o repositório do qual repl_skin lê o SKILL.md | HKUDS/CLI-Anything |