s&box CLI 是做什麼的？
專為 s&box 遊戲引擎（Facepunch Studios，Source 2）設計的 AI Agent 原生 CLI。提供 79 個以上的指令，橫跨 14 個群組。可直接操作 .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 格式（給 Agent 使用時請務必加上）
--project PATH 指定專案目錄（若省略，會從目前工作目錄的 .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
元件預設
29 個簡短名稱，可與 scene add-object、prefab new 等指令的 --components 參數搭配使用。每個名稱對應一個 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 格式回傳即時的預設註冊表。
Agent 使用模式
每次由 Agent 驅動的呼叫都請加上 --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 |