CLI de s&box
CLI nativo para agentes del motor de juego s&box (Facepunch Studios, Source 2). Más de 79 comandos en 14 grupos. Manipula archivos JSON como .scene, .prefab, .vmat, .sound, Input.config, Collision.config directamente, genera componentes C# idiomáticos y ejecuta un grafo de activos en tiempo real sobre el proyecto.
Instalación
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=sbox/agent-harness
Requisitos
- Python 3.10+
- s&box instalado a través de Steam - se detecta automáticamente, o se puede establecer
SBOX_PATHcon un directorio de instalación personalizado. - La mayoría de los comandos funcionan directamente sobre los archivos JSON del proyecto - s&box no necesita estar ejecutándose.
Opciones Globales
--json Salida JSON legible por máquina (pásala siempre para uso con agentes)
--project PATH Directorio del proyecto (se detecta automáticamente desde el cwd con .sbproj si se omite)
Grupos de Comandos
project - Gestionar proyectos s&box
cli-anything-sbox project new --name MiJuego --output-dir ./MiJuego
cli-anything-sbox --json project info
cli-anything-sbox project config --max-players 32 --tick-rate 64
cli-anything-sbox --json --project ./MiJuego project add-package facepunch.libsdf
cli-anything-sbox --json --project ./MiJuego project remove-package facepunch.libsdf
# Lint: referencias a activos rotas, GUIDs duplicados, Input.config malformado
cli-anything-sbox --json --project ./MiJuego project validate
cli-anything-sbox --project ./MiJuego project validate --no-inputs --no-guids
scene - Manipular archivos .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 Enemigo --position "100,0,0" --components "model,box_collider,rigidbody" --tags "enemy"
cli-anything-sbox scene remove-object ./scene.scene --name Enemigo
cli-anything-sbox scene add-component ./scene.scene <objeto-guid> Sandbox.PointLight
cli-anything-sbox scene remove-component ./scene.scene <objeto-guid> --component-type Sandbox.Rigidbody
cli-anything-sbox --json scene modify-object ./scene.scene --guid <guid> --name NuevoNombre --position "200,0,0"
cli-anything-sbox --json scene clone-object ./scene.scene --name Enemigo --new-name EnemigoCopia --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 <objeto-guid> <componente-guid> --properties '{"Damage":50}'
# Encuentra objetos que coincidan con uno o más filtros (combinados con AND)
cli-anything-sbox --json scene query ./scene.scene --has-component rigidbody --has-tag tower
cli-anything-sbox --json scene query ./scene.scene --name-regex "^Torre\d$" --in-bounds "0,-500,-50,1000,500,50"
# Extrae cada referencia a activo (.vmdl, .vmat, .vsnd, .vtex, .vpcf, .prefab) de una escena
cli-anything-sbox --json scene refs ./scene.scene
# Aplica la misma modificación a cada objeto que coincida con una consulta
cli-anything-sbox --json scene bulk-modify ./scene.scene --has-tag tower --position "0,0,100" --enable
# Diferencia estructural entre dos escenas (GameObjects añadidos/eliminados/modificados + SceneProperties)
cli-anything-sbox --json scene diff ./old.scene ./new.scene
# Inserta un prefab como GameObject en una escena
cli-anything-sbox --json scene instantiate-prefab ./level.scene ./Assets/prefabs/bullet.prefab --position "10,0,0"
prefab - Gestionar archivos .prefab
cli-anything-sbox prefab new --name Bala -o ./Assets/prefabs/bullet.prefab --components "model,sphere_collider,rigidbody"
cli-anything-sbox --json prefab info ./Assets/prefabs/bullet.prefab
cli-anything-sbox prefab from-scene ./scene.scene <objeto-guid> -o ./Assets/prefabs/extracted.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
# Referencias a activos dentro de un prefab
cli-anything-sbox --json prefab refs ./prefab.prefab
# Modifica propiedades de componentes en un prefab (por tipo de componente o GUID de componente)
cli-anything-sbox --json prefab modify-component ./prefab.prefab --component-type Sandbox.Rigidbody --properties '{"Gravity":false,"MassOverride":50}'
# Diferencia estructural entre dos prefabs (raíz + hijos nombrados)
cli-anything-sbox --json prefab diff ./old.prefab ./new.prefab
codegen - Generar código C#
# Componente simple
cli-anything-sbox codegen component --name ControladorJugador --methods OnUpdate,OnFixedUpdate -o ./Code/ControladorJugador.cs
# Componente con campos [Property]
cli-anything-sbox --json codegen component --name Torre --properties '[{"name":"Damage","type":"float","default":"25f"},{"name":"Range","type":"float","default":"500f"}]'
# Componente en red (clase parcial) con esqueletos de métodos RPC
cli-anything-sbox codegen component --name JugadorRed --networked --methods OnUpdate,OnFixedUpdate --rpc-methods "Firear:Transmitir,RecibirDanio:Anfitrion" -o ./Code/JugadorRed.cs
# GameResource
cli-anything-sbox codegen gameresource --name DatosTorre --display-name "Datos de Torre" --extension tower -o ./Code/DatosTorre.cs
# Menú de editor (ensamblado Editor/)
cli-anything-sbox codegen editor-menu --name MisHerramientas --menu-path "Editor/Mis Herramientas/Abrir" -o ./Editor/MisHerramientas.cs
# Componente de UI Razor simple (.razor + .razor.scss)
cli-anything-sbox codegen razor --name PanelHUD --properties '[{"name":"Puntuacion","type":"int","default":"0"}]' -o ./UI/PanelHUD.razor
# Clase estática o derivada de una base
cli-anything-sbox codegen class --name Mate2 --static -o ./Code/Mate2.cs
# PanelComponent + andamio ScreenPanel hermano (maneja la peculiaridad de s&box donde
# la entrada de PanelComponent solo funciona cuando ambos están en el mismo GameObject).
# Emite .razor + .razor.scss + un fragmento de GameObject listo para pegar, o añade
# directamente a una escena con --scene.
cli-anything-sbox --json codegen panel-component --name BarraHUD -o ./UI/BarraHUD.razor
cli-anything-sbox codegen panel-component --name Mira -o ./UI/Mira.razor --scene ./Assets/scenes/game.scene
input - Gestionar Input.config
cli-anything-sbox --json input list
cli-anything-sbox input add --name ColocarTorre --group Gameplay --keyboard mouse1 --gamepad RightTrigger
cli-anything-sbox input remove --name ColocarTorre
cli-anything-sbox input set --name Ataque1 --keyboard mouse1
collision - Gestionar Collision.config
cli-anything-sbox --json collision list
cli-anything-sbox collision add-layer --name proyectil --default Colisionar
cli-anything-sbox collision add-rule --layer-a proyectil --layer-b solido --result Colisionar
cli-anything-sbox collision remove-rule --layer-a proyectil --layer-b solido
cli-anything-sbox collision remove-layer --name proyectil
material - Gestionar materiales .vmat
cli-anything-sbox --json material new --name suelo --shader complex --color-texture "textures/suelo.tga" --metalness 0.3 -o ./Assets/materials/suelo.vmat
cli-anything-sbox --json material info ./Assets/materials/suelo.vmat
cli-anything-sbox --json material list
cli-anything-sbox --json material set ./Assets/materials/suelo.vmat --metalness 0.8
sound - Gestionar eventos .sound
cli-anything-sbox --json sound new --name disparo --sounds "sounds/disparo1.vsnd,sounds/disparo2.vsnd" --volume 0.8 -o ./Assets/sounds/disparo.sound
cli-anything-sbox --json sound info ./Assets/sounds/disparo.sound
cli-anything-sbox --json sound list
cli-anything-sbox --json sound set ./Assets/sounds/disparo.sound --volume 0.5
localization - Gestionar traducciones
cli-anything-sbox localization new --lang es -o ./Localization/es.json
cli-anything-sbox localization set ./Localization/es.json --key "juego.titulo" --value "Mi Juego"
cli-anything-sbox --json localization list ./Localization/es.json
cli-anything-sbox localization get ./Localization/es.json --key "juego.titulo"
cli-anything-sbox localization remove ./Localization/es.json --key "juego.titulo"
cli-anything-sbox localization bulk-set ./Localization/es.json --keys '{"ui.iniciar":"Iniciar","ui.salir":"Salir"}'
server - Servidor dedicado
cli-anything-sbox server info
cli-anything-sbox server start --game mi_juego --map facepunch.flatgrass
asset - Gestión de activos y búsquedas inversas
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/suelo.vmat
# ¿Qué escenas/prefabs referencian este activo?
cli-anything-sbox --json --project ./MiJuego asset find-refs models/miequipo/widget.vmdl
# Encuentra activos no referenciados (por tipo, o en todos los tipos referenciables)
cli-anything-sbox --json --project ./MiJuego asset find-unused
cli-anything-sbox --json --project ./MiJuego asset find-unused --type model --type material
# Renombra un activo y actualiza todas las referencias en escenas/prefabs (la extensión se conserva si se omite)
cli-anything-sbox --json --project ./MiJuego asset rename models/equipo/widget.vmdl artilugio
cli-anything-sbox --project ./MiJuego asset rename models/equipo/widget.vmdl artilugio --dry-run
# Mueve un activo entre directorios y actualiza todas las referencias
cli-anything-sbox --json --project ./MiJuego asset move models/equipo/widget.vmdl models/compartido/widget.vmdl
session - Gestión de estado
cli-anything-sbox session status
cli-anything-sbox session undo
cli-anything-sbox session redo
test - Herramienta automatizada de generación de mapas/escenas
cli-anything-sbox test setup
cli-anything-sbox --json test run
launch - Abrir proyecto en el editor de s&box
cli-anything-sbox launch
Preajustes de Componentes
29 nombres cortos utilizables con --components en scene add-object, prefab new, etc. Cada uno se asigna a un tipo de componente Sandbox.*.
| Preajuste | 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 devuelve el registro de preajustes en vivo como JSON.
Patrón de Uso para Agentes
Pasa --json en cada invocación impulsada por un agente. Canaliza a través de jq para enhebrar GUIDs y rutas entre comandos:
# Inicializar un proyecto
sbproj=$(cli-anything-sbox --json project new --name MiJuego --output-dir /tmp/MiJuego | jq -r '.sbproj')
cd /tmp/MiJuego
# Añadir una torre con una disposición de componentes específica, capturar su GUID
guid=$(cli-anything-sbox --json scene add-object ./Assets/scenes/main.scene Torre \
--components "model,box_collider,rigidbody" --tags "tower" \
| jq -r '.guid')
# Generar el componente C# correspondiente, en red
cli-anything-sbox --json codegen component --name Torre --networked \
--rpc-methods "Firear:Anfitrion" --properties '[{"name":"Damage","type":"float","default":"25f"}]' \
-o ./Code/Torre.cs
# Ajuste masivo de cada torre en la escena
cli-anything-sbox --json scene bulk-modify ./Assets/scenes/main.scene \
--has-tag tower --enable --position-y-add 50
# Validar antes de confirmar
cli-anything-sbox --json project validate
Modo REPL
cli-anything-sbox sin argumentos entra en un REPL interactivo con un 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
Variables de Entorno
| Variable | Descripción | Valor por Defecto |
|---|---|---|
SBOX_PATH | Directorio de instalación de s&box | Detectado automáticamente desde las carpetas de la biblioteca de Steam |
CLI_ANYTHING_SKILL_REPO | Sobrescribe el repositorio del que repl_skin lee SKILL.md | HKUDS/CLI-Anything |