s&box CLI은(는) 무엇을 하나요?
s&box 게임 엔진(Facepunch Studios, Source 2)을 위한 에이전트 네이티브 CLI입니다. 14개 그룹에 걸친 79개 이상의 명령어를 통해 .scene, .prefab, .vmat, .sound, Input.config, Collision.config JSON 파일을 직접 조작하고, 관용적인 C# 컴포넌트를 생성하며, 프로젝트에서 실시간 에셋 그래프를 실행할 수 있습니다.
설치
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=sbox/agent-harness
요구 사항
- Python 3.10+
- Steam을 통해 설치된 s&box - 자동 감지되거나,
SBOX_PATH를 설정하여 사용자 지정 설치 디렉토리를 지정할 수 있습니다. - 대부분의 명령어는 프로젝트의 JSON 파일에서만 작동합니다 - s&box가 실행 중일 필요가 없습니다.
전역 옵션
--json 기계가 읽을 수 있는 JSON 출력 (에이전트 사용 시 항상 전달)
--project PATH 프로젝트 디렉토리 (생략 시 cwd의 .sbproj에서 자동 감지)
명령어 그룹
project - s&box 프로젝트 관리
cli-anything-sbox project new --name MyGame --output-dir ./MyGame
cli-anything-sbox --json project info
cli-anything-sbox project config --max-players 32 --tick-rate 64
cli-anything-sbox --json --project ./MyGame project add-package facepunch.libsdf
cli-anything-sbox --json --project ./MyGame project remove-package facepunch.libsdf
# 린트: 깨진 에셋 참조, 중복 GUID, 잘못된 Input.config
cli-anything-sbox --json --project ./MyGame project validate
cli-anything-sbox --project ./MyGame project validate --no-inputs --no-guids
scene - .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 Enemy --position "100,0,0" --components "model,box_collider,rigidbody" --tags "enemy"
cli-anything-sbox scene remove-object ./scene.scene --name Enemy
cli-anything-sbox scene add-component ./scene.scene <object-guid> Sandbox.PointLight
cli-anything-sbox scene remove-component ./scene.scene <object-guid> --component-type Sandbox.Rigidbody
cli-anything-sbox --json scene modify-object ./scene.scene --guid <guid> --name NewName --position "200,0,0"
cli-anything-sbox --json scene clone-object ./scene.scene --name Enemy --new-name EnemyCopy --position "300,0,0"
cli-anything-sbox --json scene get-object ./scene.scene --name Sun
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 <object-guid> <component-guid> --properties '{"Damage":50}'
# 하나 이상의 필터(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 "^Tower\d$" --in-bounds "0,-500,-50,1000,500,50"
# 씬에서 모든 에셋 참조(.vmdl, .vmat, .vsnd, .vtex, .vpcf, .prefab) 추출
cli-anything-sbox --json scene refs ./scene.scene
# 쿼리와 일치하는 모든 오브젝트에 동일한 수정 적용
cli-anything-sbox --json scene bulk-modify ./scene.scene --has-tag tower --position "0,0,100" --enable
# 두 씬 간의 구조적 차이(추가/제거/수정된 GameObject + SceneProperties)
cli-anything-sbox --json scene diff ./old.scene ./new.scene
# 씬에 프리팹을 GameObject로 삽입
cli-anything-sbox --json scene instantiate-prefab ./level.scene ./Assets/prefabs/bullet.prefab --position "10,0,0"
prefab - .prefab 파일 관리
cli-anything-sbox prefab new --name Bullet -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 <object-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
# 프리팹 내부의 에셋 참조
cli-anything-sbox --json prefab refs ./prefab.prefab
# 프리팹의 컴포넌트 속성 수정(컴포넌트 유형 또는 컴포넌트 GUID 기준)
cli-anything-sbox --json prefab modify-component ./prefab.prefab --component-type Sandbox.Rigidbody --properties '{"Gravity":false,"MassOverride":50}'
# 두 프리팹 간의 구조적 차이(루트 + 명명된 자식)
cli-anything-sbox --json prefab diff ./old.prefab ./new.prefab
codegen - C# 코드 생성
# 일반 컴포넌트
cli-anything-sbox codegen component --name PlayerController --methods OnUpdate,OnFixedUpdate -o ./Code/PlayerController.cs
# [Property] 필드가 있는 컴포넌트
cli-anything-sbox --json codegen component --name Tower --properties '[{"name":"Damage","type":"float","default":"25f"},{"name":"Range","type":"float","default":"500f"}]'
# 네트워크 컴포넌트(부분 클래스) + 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 "Tower Data" --extension tower -o ./Code/TowerData.cs
# 에디터 메뉴(Editor/ 어셈블리)
cli-anything-sbox codegen editor-menu --name MyTools --menu-path "Editor/My Tools/Open" -o ./Editor/MyTools.cs
# 일반 Razor UI 컴포넌트(.razor + .razor.scss)
cli-anything-sbox codegen razor --name HudPanel --properties '[{"name":"Score","type":"int","default":"0"}]' -o ./UI/HudPanel.razor
# 정적 또는 기본 클래스 파생 클래스
cli-anything-sbox codegen class --name Math2 --static -o ./Code/Math2.cs
# PanelComponent + 형제 ScreenPanel 스캐폴드(s&box의 특수성 처리:
# PanelComponent 입력은 둘 다 동일한 GameObject에 있을 때만 작동함).
# .razor + .razor.scss + 붙여넣기 가능한 GameObject 스니펫을 내보내거나,
# --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 - 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 - Collision.config 관리
cli-anything-sbox --json collision list
cli-anything-sbox collision add-layer --name projectile --default Collide
cli-anything-sbox collision add-rule --layer-a projectile --layer-b solid --result Collide
cli-anything-sbox collision remove-rule --layer-a projectile --layer-b solid
cli-anything-sbox collision remove-layer --name projectile
material - .vmat 머티리얼 관리
cli-anything-sbox --json material new --name floor --shader complex --color-texture "textures/floor.tga" --metalness 0.3 -o ./Assets/materials/floor.vmat
cli-anything-sbox --json material info ./Assets/materials/floor.vmat
cli-anything-sbox --json material list
cli-anything-sbox --json material set ./Assets/materials/floor.vmat --metalness 0.8
sound - .sound 이벤트 관리
cli-anything-sbox --json sound new --name gunshot --sounds "sounds/gun1.vsnd,sounds/gun2.vsnd" --volume 0.8 -o ./Assets/sounds/gunshot.sound
cli-anything-sbox --json sound info ./Assets/sounds/gunshot.sound
cli-anything-sbox --json sound list
cli-anything-sbox --json sound set ./Assets/sounds/gunshot.sound --volume 0.5
localization - 번역 관리
cli-anything-sbox localization new --lang en -o ./Localization/en.json
cli-anything-sbox localization set ./Localization/en.json --key "game.title" --value "My Game"
cli-anything-sbox --json localization list ./Localization/en.json
cli-anything-sbox localization get ./Localization/en.json --key "game.title"
cli-anything-sbox localization remove ./Localization/en.json --key "game.title"
cli-anything-sbox localization bulk-set ./Localization/en.json --keys '{"ui.start":"Start","ui.quit":"Quit"}'
server - 전용 서버
cli-anything-sbox server info
cli-anything-sbox server start --game my_game --map facepunch.flatgrass
asset - 에셋 관리 및 역참조
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/floor.vmat
# 이 에셋을 참조하는 씬/프리팹은?
cli-anything-sbox --json --project ./MyGame asset find-refs models/myteam/widget.vmdl
# 참조되지 않은 에셋 찾기(유형별 또는 모든 참조 가능 유형 전체)
cli-anything-sbox --json --project ./MyGame asset find-unused
cli-anything-sbox --json --project ./MyGame asset find-unused --type model --type material
# 에셋 이름을 바꾸고 모든 씬/프리팹 참조 업데이트(생략 시 확장자 유지)
cli-anything-sbox --json --project ./MyGame asset rename models/team/widget.vmdl gizmo
cli-anything-sbox --project ./MyGame asset rename models/team/widget.vmdl gizmo --dry-run
# 에셋을 디렉토리 간에 이동하고 모든 참조 업데이트
cli-anything-sbox --json --project ./MyGame asset move models/team/widget.vmdl models/shared/widget.vmdl
session - 상태 관리
cli-anything-sbox session status
cli-anything-sbox session undo
cli-anything-sbox session redo
test - 자동화된 맵/씬 생성 도구
cli-anything-sbox test setup
cli-anything-sbox --json test run
launch - s&box 편집기에서 프로젝트 열기
cli-anything-sbox launch
컴포넌트 프리셋
scene add-object, prefab new 등에서 --components와 함께 사용할 수 있는 29개의 짧은 이름입니다. 각각은 Sandbox.* 컴포넌트 유형에 매핑됩니다.
| 프리셋 | 컴포넌트 유형 |
|---|---|
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는 라이브 프리셋 레지스트리를 JSON으로 반환합니다.
에이전트 사용 패턴
모든 에이전트 기반 호출에는 --json을 전달하세요. jq를 통해 파이핑하여 GUID와 경로를 명령 간에 연결합니다:
# 프로젝트 부트스트랩
sbproj=$(cli-anything-sbox --json project new --name MyGame --output-dir /tmp/MyGame | jq -r '.sbproj')
cd /tmp/MyGame
# 특정 컴포넌트 레이아웃으로 타워 추가, GUID 캡처
guid=$(cli-anything-sbox --json scene add-object ./Assets/scenes/main.scene Tower \
--components "model,box_collider,rigidbody" --tags "tower" \
| jq -r '.guid')
# 해당 C# 컴포넌트 생성, 네트워크 지원
cli-anything-sbox --json codegen component --name Tower --networked \
--rpc-methods "Fire:Host" --properties '[{"name":"Damage","type":"float","default":"25f"}]' \
-o ./Code/Tower.cs
# 씬의 모든 타워를 대량 수정
cli-anything-sbox --json scene bulk-modify ./Assets/scenes/main.scene \
--has-tag tower --enable --position-y-add 50
# 커밋 전 검증
cli-anything-sbox --json project validate
REPL 모드
cli-anything-sbox를 인수 없이 실행하면 스타일이 지정된 프롬프트로 대화형 REPL이 시작됩니다:
$ 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
환경 변수
| 변수 | 설명 | 기본값 |
|---|---|---|
SBOX_PATH | s&box 설치 디렉토리 | Steam 라이브러리 폴더에서 자동 감지 |
CLI_ANYTHING_SKILL_REPO | repl_skin이 SKILL.md를 읽어올 저장소 재정의 | HKUDS/CLI-Anything |