BesiegeField

<div align="center"> <img src="assets/BesiegeField_logo.png" alt="BesiegeField Logo" width="50%"> </div> <div align="center">

The First Framework for LLM-Driven Machine Design in Besiege

Paper: Agentic Design of Compositional Machines

<a href="https://arxiv.org/abs/2510.14980"><img src="https://img.shields.io/badge/arXiv-2510.14980-b31b1b?style=flat-square&logo=arxiv&logoColor=white"></a> <a href="https://besiegefield.github.io/"><img src="https://img.shields.io/badge/Project-Website-42a5f5?style=flat-square&logo=firefox&logoColor=white"></a> <a href="https://huggingface.co/spaces/Godheritage/BesiegeField-MachineGenerator"><img src="https://img.shields.io/badge/🤗-HuggingFace%20Demo-ff9800?style=flat-square"></a> <a href="https://huggingface.co/Godheritage/models"><img src="https://img.shields.io/badge/🤗-Catapult RL%20Model-ff9800?style=flat-square"></a> <a href="https://huggingface.co/BesiegeField/Qwen2.5-14B-Instruct-BesiegeField-CarRL"><img src="https://img.shields.io/badge/🤗-Car RL%20Model-ff9800?style=flat-square"></a>

Installation • Quick Start • Training • Citation

</div> <p align="center"> <img src="https://github.com/Godheritage/BesiegeField/blob/main/assets/throwing.gif?raw=true" alt="Demo animation" width="800"> </p>

---

📋 Table of Contents

• Overview
• Installation
  • Besiege Environment Setup
  • AgenticFlow Installation
• Quick Start
• Fine-tuning
• Performance Leaderboard
• RL Fine-tuning Results
• License
• Acknowledgement
• Citation

---

🌟 Overview

BesiegeField is a cutting-edge framework that enables Large Language Models (LLMs) to autonomously design and build complex machines in the Besiege physics-based game environment. This project bridges AI reasoning with creative engineering tasks.

---

🚀 Installation

1. Besiege Environment Setup

📦 System Requirements

| Component | Version | |-----------|---------| | Besiege | Linux v1.60-22044 | | Ubuntu | 22.04 | | GLIBC | 2.33 – 2.35 | | Mono | ≥ 6.8.0.105 |

🎯 Obtain the Game

Step 1: Purchase the official copy on Steam

Step 2: Download DepotDownloader

Step 3: Download Besiege v1.60-22044

./DepotDownloader -app 346010 -depot 346016 -manifest 2732248020700221971 \
  -username <steam_user> -password <password>

Step 4: Download v1.20-17395 executables (required for headless operation)

./DepotDownloader -app 346010 -depot 346016 -manifest 5506301120812842666 \
  -username <steam_user> -password <password>

💡 Tip: Find other manifests on SteamDB if needed.

🔌 Download the Plugin

📥 BesiegeField Plugin (Google Drive)

🛠️ Install Dependencies

Standard Installation:

sudo apt install mono-complete xvfb  # xvfb only for headless workstation
mono --version  # Verify ≥ 6.8.0.105

<details> <summary>📦 <b>Offline/Manual Installation</b> (click to expand)</summary>

If apt is unavailable, use manual installation:

# Install mono
cd /path/to/tar
tar -xzf mono-complete-offline.tar.gz
for deb in *.deb; do dpkg -x "$deb" .; done

export PATH="/path/to/mono/usr/bin:$PATH"
export LD_LIBRARY_PATH="/path/to/mono/usr/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/path/to/mono/usr/lib/pkgconfig:$PKG_CONFIG_PATH"

# Make permanent
cat >> ~/.bashrc <<EOF
export PATH="/path/to/mono/usr/bin:\$PATH"
export LD_LIBRARY_PATH="/path/to/mono/usr/lib:\$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="/path/to/mono/usr/lib/pkgconfig:\$PKG_CONFIG_PATH"
EOF
source ~/.bashrc

# Install xvfb
cd /path/to/xvfb
tar -xzf xvfb-offline.tar.gz
dpkg -i *.deb

</details>

⚙️ Install BesiegeField Plugin

Step 1: Extract the plugin archive and copy all files into the v1.60-22044 game folder

Step 2: Copy Besiege.x86 & Besiege.x86_64 from v1.20-17395 into v1.60-22044, overwriting the originals

⚠️ Warning: This enables headless/code control but makes normal GUI start unstable. Keep a backup if you want to launch v1.60 visually.

Step 3: Set permissions

chmod -R 777 /path/to/Besiege

Step 4: Test the vanilla game (use backup copy)

cd /path/to/backup/Besiege && ./run.sh

---

2. AgenticFlow Installation

🐍 Create Conda Environment

conda env create -f environment_inferenceonly.yaml
conda activate <env_name>

📂 Path Configuration

Folder Structure:

your-project/
├── Besiege/                  # Game installation
└── AgenticCodes/             # Framework code

Edit AgenticCodes/config.py:

| Parameter | Description | |-----------|-------------| | APIPATH | Path to file storing LLM type, API key, etc. Fill it in yourself. | | DEFAULT_SAVE_ROOT | Root directory for LLM outputs | | SCRIPT_PATH | Must point to Besiege/run_besiegefield.sh |

---

🎯 Quick Start

🏹 Catapult Task

Design a machine to throw projectiles:

python main.py \
  -use_model deepseek-chat \
  -task catapult/catapult_level1 \
  -env_num 2 \
  -user_input "Design a machine to throw a boulder (type id 36) in a parabolic trajectory."

🚗 Car Task

Design a machine to move forward:

python main.py \
  -use_model deepseek-chat \
  -task car/car_level1 \
  -env_num 2 \
  -user_input "Design a machine to move forward on a straight road."

📝 Available Tasks

Explore all available tasks in environments/env_files/level_menus.json

🎮 Testing Your Designs

1. Generated .bsg machine files appear in DEFAULT_SAVE_ROOT
2. Copy them to Besiege/Besiege_Data/SavedMachines
3. Run ./run.sh to launch the game
4. Inspect and test your AI-designed machines in-game!

---

🔧 LLM Fine-tuning

📦 Install Training Environment

Add training-related packages:

conda activate <env_name>
pip install -r requirements_rl.txt

---

❄️ Cold Start Training

<!-- #### Step 1: Download Dataset ```bash cd PostTraining/ColdStart/dataset ./download_dataset.sh ``` -->

Step 1: Run Cold Start with Orthogonal Finetuning (Dataset will download from huggingface)

cd PostTraining/ColdStart
./run_cold_start.sh <model_path>

If you want to try cold start with human dataset (Not Recommended), you can run with:

cd PostTraining/ColdStart
./run_cold_start.sh <model_path> true

Step 2: Merge Checkpoints

Fill the paths in merge_ckpts.py before running:

python merge_ckpts.py

---

🎓 Reinforcement Learning

Configure rl_config.yaml with your settings (important!), then run:

cd PostTraining/RL
./rl_single_agent_light.sh

---

📊 Performance Leaderboard

🎯 Catapult Task

Performance metrics across different models and methods:

<table> <thead> <tr> <th rowspan="2" align="left">Models</th> <th colspan="3" align="center"><b>Single-agent</b></th> <th colspan="3" align="center"><b>Iterative Editing</b></th> <th colspan="3" align="center"><b>Hierarchical Design</b></th> </tr> <tr> <th align="center"><b>Mean</b></th> <th align="center"><b>Max</b></th> <th align="center"><b>Std</b></th> <th align="center"><b>Mean</b></th> <th align="center"><b>Max</b></th> <th align="center"><b>Std</b></th> <th align="center"><b>Mean</b></th> <th align="center"><b>Max</b></th> <th align="center"><b>Std</b></th> </tr> </thead> <tbody> <tr> <td><b>Gemini 2.5 Pro</b></td> <td align="center">2.30</td> <td align="center">9.00</td> <td align="center">3.86</td> <td align="center">4.67</td> <td align="center"><b>21.95</b></td> <td align="center">8.68</td> <td align="center"><b>9.83</b></td> <td align="center"><b>18.19</b></td> <td align="center">8.35</td> </tr> <tr> <td><b>OpenAI o3</b></td> <td align="center">2.87</td> <td align="center">5.22</td> <td align="center">1.96</td> <td align="center"><b>9.14</b></td> <td align="center">14.01</td> <td align="center">3.71</td> <td align="center">2.00</td> <td align="center">11.11</td> <td align="center">3.98</td> </tr> <tr> <td><b>Qwen3-Coder-480B-A35B</b></td> <td align="center">1.75</td> <td align="center">9.24</td> <td align="center">3.17</td> <td align="center">5.10</td> <td align="center">12.02</td> <td align="center">5.54</td> <td align="center">3.90</td> <td align="center">6.52</td> <td align="center">2.54</td> </tr> <tr> <td><b>Doubao Seed 1.6-250615</b></td> <td align="center">3.18</td> <td align="center">8.20</td> <td align="center">2.99</td> <td align="center">4.82</td> <td align="center">9.10</td> <td align="center">3.41</td> <td align="center">1.73</td> <td align="center">4.76</td> <td align="center">2.39</td> </tr> <tr> <td><b>Claude Opus 4-20250514</b></td> <td align="center">1.19</td> <td align="center">4.82</td> <td align="center">2.21</td> <td align="center">1.18</td> <td align="center">4.91</td> <td align="center">2.18</td> <td align="center">2.27</td> <td ali