Make permanent

📋 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

🎯 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

# 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

⚙️ 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:

🎯 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: 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:

🚗 Car Task

Performance metrics across different models and methods:

🎓 RL-Finetuned LLM Results

Performance comparison of Qwen2.5-14B-Instruct model with different training strategies:

📚 Citation

If you find this repository useful for your research or projects, please consider citing our work:

@article{zhang2025besiegefield,
  title={Agentic Design of Compositional Machines},
  author={Zhang, Wenqian and Liu, Weiyang and Liu, Zhen},
  journal={arXiv preprint arXiv:2510.14980},
  year={2025}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgement

We’d like to thank the developers of Besiege for creating such an inspiring game and for nurturing such a vibrant player community — without them, this project wouldn’t exist.

Big thanks also to the BepInEx team for their amazing modding framework, which made it possible for us to push the boundaries of what’s possible in Besiege.

⭐ Star History

If you find this project helpful, please consider giving it a star! ⭐

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License - see the LICENSE file for details.