Gsp dev

.clang-format

@@ -0,0 +1,13 @@
+# Defines the code style for C/C++/CUDA section
+---
+Language: Cpp
+BasedOnStyle: LLVM
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ColumnLimit: 120
+SortIncludes: false
+---
+Language: Json
+# Don't format .json files
+DisableFormat: true

.clang-format-ignore

@@ -0,0 +1,2 @@
+# Pufferlib extensions
+pufferlib/extensions/**

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [2.0]
+    paths: [docs/**]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book

.gitignore

@@ -161,13 +161,19 @@ pufferlib/ocean/impulse_wars/debug-*/
 pufferlib/ocean/impulse_wars/release-*/
 pufferlib/ocean/impulse_wars/benchmark/
 
-
 # Ignore data files
 data/
 pufferlib/resources/drive/binaries/
+pufferlib/resources/drive/binaries/training/
+pufferlib/resources/drive/binaries/validation/
 
 # But keep map_000.bin for the training test
 !pufferlib/resources/drive/binaries/map_000.bin
+!pufferlib/resources/drive/binaries/training/map_000.bin
+pufferlib/resources/drive/sanity/sanity_binaries/
+
+# Ignore human demonstration data
+pufferlib/resources/drive/human_demonstrations/*
 
 # Compiled drive binary in root
 /drive
@@ -184,3 +190,6 @@ pufferlib/resources/drive/output_agent.gif pufferlib/resources/drive/output.gif
 artifacts/
 # Local drive renders
 pufferlib/resources/drive/output*.gif
+emsdk/
+docs/book/*
+!docs/book/assets/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/pyxodr"]
+	path = external/pyxodr
+	url = https://github.com/mpragnay/pyxodr.git

.pre-commit-config.yaml

@@ -21,3 +21,9 @@ repos:
     - id: nb-clean
       args:
         - --remove-empty-cells
+# Apply clang format
+- repo: https://github.com/pre-commit/mirrors-clang-format
+  rev: 'v21.1.5'
+  hooks:
+  -   id: clang-format
+      exclude: '\.(js|html)$|^build_web/|^docs/assets/'

README.md

@@ -1,5 +1,33 @@
 # PufferDrive
 
+[![Unit Tests](https://github.com/Emerge-Lab/PufferDrive/actions/workflows/utest.yml/badge.svg)](https://github.com/Emerge-Lab/PufferDrive/actions/workflows/utest.yml)
+
+<img align="left" style="width:260px" src="https://github.com/Emerge-Lab/PufferDrive/blob/main/pufferlib/resources/drive/pufferdrive_20fps_long.gif" width="288px">
+
+**PufferDrive is a fast and friendly driving simulator to train and test RL-based models.**
+
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+<br>
+
+---
+
+**Docs**: https://emerge-lab.github.io/PufferDrive
+
+---
+
+### See our 2.0 release video
+
+<a href="https://www.youtube.com/watch?v=LfQ324R-cbE">
+  <img src="https://img.youtube.com/vi/LfQ324R-cbE/0.jpg" alt="PufferDrive 2.0" width="300">
+</a>
 
 ## Installation
 
@@ -22,6 +50,7 @@ Compile the C code
 ```
 python setup.py build_ext --inplace --force
 ```
+Run this while your virtual environment is active so the extension is built against the right interpreter.
 
 To test your setup, you can run
 ```
@@ -54,8 +83,9 @@ python pufferlib/ocean/drive/drive.py
 
 You can download the WOMD data from Hugging Face in two versions:
 
-- **Mini Dataset**: [GPUDrive_mini](https://huggingface.co/datasets/EMERGE-lab/GPUDrive_mini) contains 1,000 training files and 300 test/validation files
-- **Full Dataset**: [GPUDrive](https://huggingface.co/datasets/EMERGE-lab/GPUDrive) contains 100,000 unique scenes
+- **Mini dataset**: [GPUDrive_mini](https://huggingface.co/datasets/EMERGE-lab/GPUDrive_mini) contains 1,000 training files and 300 test/validation files
+- **Medium dataset**: [10,000 files from the training dataset](https://huggingface.co/datasets/daphne-cornelisse/pufferdrive_train)
+- **Large dataset**: [GPUDrive](https://huggingface.co/datasets/EMERGE-lab/GPUDrive) contains 100,000 unique scenes
 
 **Note**: Replace 'GPUDrive_mini' with 'GPUDrive' in your download commands if you want to use the full dataset.
 
@@ -70,6 +100,19 @@ For more training data compatible with PufferDrive, see [ScenarioMax](https://gi
 <details>
 <summary>Dependencies and usage</summary>
 
+## Local rendering
+
+To launch an interactive renderer, first build:
+```
+bash scripts/build_ocean.sh drive local
+```
+
+then launch:
+```bash
+./drive
+```
+this will run `demo()` with an existing model checkpoint.
+
 ## Headless server setup
 
 Run the Raylib visualizer on a headless server and export as .mp4. This will rollout the pre-trained policy in the env.
@@ -117,7 +160,7 @@ The `-s` flag sets up a virtual screen at 1280x720 resolution with 24-bit color
 
 ### Distributional realism
 
-We provide a PufferDrive implementation of the [Waymo Open Sim Agents Challenge (WOSAC)](https://waymo.com/open/challenges/2025/sim-agents/) for fast, easy evaluation of how well your trained agent matches distributional properties of human behavior. See details [here](https://github.com/Emerge-Lab/PufferDrive/tree/main/pufferlib/ocean/benchmark).
+We provide a PufferDrive implementation of the [Waymo Open Sim Agents Challenge (WOSAC)](https://waymo.com/open/challenges/2025/sim-agents/) for fast, easy evaluation of how well your trained agent matches distributional properties of human behavior. See documentation [here](https://emerge-lab.github.io/PufferDrive/wosac/).
 
 WOSAC evaluation with random policy:
 ```bash
@@ -135,3 +178,41 @@ You may be interested in how compatible your agent is with human partners. For t
 ```bash
 puffer eval puffer_drive --eval.human-replay-eval True --load-model-path <your-trained-policy>.pt
 ```
+
+## Development
+
+<details><summary>Documentation and browser demo</summary>
+
+**Docs**
+
+A browsable documentation site now lives under `docs/` and is configured with mkbooks. To preview locally:
+```
+brew install mdbook
+mdbook serve --open docs
+```
+Open the served URL to see a local version of the docs.
+
+**Interactive demo**
+
+To edit the browser demo, follow these steps:
+- Download [emscripten](https://github.com/emscripten-core/emscripten)
+- emscripten install latest
+- Activate: `source emsdk/emsdk_env.sh`
+- Run `bash scripts/build_ocean.sh drive web`
+- This generates a number of `game*` files, move them to `assets/` to include them on the webpage
+
+</details>
+
+
+## Citation
+
+If you use PufferDrive in your research, please cite:
+```bibtex
+@software{pufferdrive2025github,
+  author = {Daphne Cornelisse* and Spencer Cheng* and Pragnay Mandavilli and Julian Hunt and Kevin Joseph and Waël Doulazmi and Valentin Charraut and Aditya Gupta and Joseph Suarez and Eugene Vinitsky},
+  title = {{PufferDrive}: A Fast and Friendly Driving Simulator for Training and Evaluating {RL} Agents},
+  url = {https://github.com/Emerge-Lab/PufferDrive},
+  version = {2.0.0},
+  year = {2025},
+}
+```