Runespawn is a framework for coordinating agents to automatically write code for Unity games. It is loosely based on the Voyager framework, with extensive additions.

Setup

Python environment

python -m venv rs

# Activate virtual environment (Windows)
rs\Scripts\activate

# Activate virtual environment (Linux/macOS)
source rs/bin/activate

# Install required packages
pip install -r requirements.txt

Unity Project Setup

1. Import Experimental Runespawn Package

   • Open the Unity Package Manager, select "Add package from disk", and import the Runespawn package by selecting the RGUnityBots\src\gg.regression.unity.experimental.runespawn\package.json file.
   • After importing, check the Unity console to confirm that the TCP Listener has initialized successfully.

2. [Optional] Configure Script Exporter

   • In your Unity project, go to Create > Script Exporter > Config
   • This will create a new ScriptExporterConfig scriptable object
   • Add the scripts you want to export to this configuration.
   • These are the scripts that Runespawn will definitely, and always, see.
   • Runespawn will always index all .CS files in the project root, and will try to retreive relevant ones for context.

3. Record and Save Replay

   • Record a gameplay replay in your Unity project.
   • Move the recorded replay file to the recordings folder within the Runespawn directory.
   • This will include the game objects runespawn will be able to see.

4. Add the Runespawn Script to a game object.

   • Runespawn will create a script in the place defined by the workspace.test_file in the config.
   • You can create a default Unity script in this location and add it to a empty game object in your scene.
   • When you run Runespawn, it will save the created script to this location.

Create a new config.

Copy one of the existing configs and modify it. Likely you will have to change the following fields:

"replay_folder_path": "runespawn/recordings/<path to your recording file>",
"workspace": {
    "project_root": "<path to your Unity project root>",
},
"game_information": {
    "name": "<name of the game>",
    "genre": "<genre of the game>",
    "camera_perspective": "<camera perspective of the game>",
    "platform": "<platform of the game>",
    "description": "<description of the game>",
    "goal": "<goal of the game>",
    "game_mode": "<game mode of the game>",
    "notes_about_AI_implementation": "<notes about AI implementation>"
  }

Langsmith Experiment Tracking

# For Windows (PowerShell)
$env:LANGCHAIN_TRACING_V2="true"
$env:LANGCHAIN_API_KEY="<LangSmith API key>"
$env:LANGCHAIN_PROJECT="Runespawn"

# For Unix (Bash)
export LANGCHAIN_TRACING_V2="true"
export LANGCHAIN_API_KEY="<LangSmith API key>"
export LANGCHAIN_PROJECT="Runespawn"

Set these environment variables permanently by adding them to your shell's configuration file (e.g., .bashrc or .zshrc).

How to use?

Simply run python main.py which is the following:

from runespawn import Runespawn

r = Runespawn("configs/<path to your config>.json")
overarching_goal = "<your goal for this session>"   
first_task = "<the first task runespawn should complete>"
r.run(overarching_goal, first_task)

How to run an experiment

Experiments allow you to evaluate Runespawn's performance across different configurations and tasks. Here's how to run one:

1. Create an experiment config file (JSON format):

{
  "experiment_name": "Test Experiment",
  "description": "This experiment compares different configurations and prompts",
  "session_config_paths": [
    "configs/micro_platformer.json"
  ],
  "tasks": [
    {
      "name": "Collect Token - Basic Prompt",
      "prompt": "Collect a token.",
      "success_criteria": "Token collected!",
      "episode_length": 10,
      "num_repetitions": 5
    },
    {
      "name": "Collect Token - Step by Step Prompt",
      "prompt": "Move until you are underneath a token, then jump and collect it.",
      "success_criteria": "Token collected!",
      "episode_length": 10,
      "num_repetitions": 5
    }
  ]
}

2. Run the experiment using one of these methods:

from runespawn.evaluation import ExperimentRunner

experiment = ExperimentRunner("<path to your experiment config>")
experiment_results = experiment.run()

The experiment will:

• Run each task with each configuration
• Repeat each task-config pair the specified number of times
• Save results to runespawn/evaluation/experiment_results/<experiment_name>/<timestamp>/
• Generate a summary of success rates by task and configuration

Results can be loaded and analyzed later:

from runespawn.evaluation.eval_datatypes import ExperimentResults

results = ExperimentResults.load("path/to/experiment_results.json")
print(results.summary())

For more detailed analysis examples, see the evaluation helper notebook at runespawn/notebooks/03_evaluation_helper.ipynb.

Running Tests

pytest