pjsny · pjsny · Jan 1, 2026 · Jan 1, 2026
diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml
@@ -0,0 +1,91 @@
+name: Python Bindings
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  build:
+    name: Build / ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux
+          - os: macos-latest
+            name: macOS
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Build wheel
+        run: |
+          cd python
+          uv build --wheel
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}
+          path: python/dist/*.whl
+
+  test:
+    name: Test / ${{ matrix.name }}
+    needs: build
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            name: Linux
+          - os: macos-latest
+            name: macOS
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Download wheel
+        uses: actions/download-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}
+          path: python/dist
+
+      - name: Install dependencies
+        run: |
+          cd python
+          uv venv
+          uv pip install dist/*.whl pytest numpy
+
+      - name: Run tests
+        run: |
+          cd python
+          source .venv/bin/activate
+          pytest tests/ -v
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,14 +1,13 @@
-name: Tests
+name: C++ Core
 
 on:
   push:
-    branches: [main, master, develop]
+    branches: [main, master]
   pull_request:
-    branches: [main, master, develop]
 
 jobs:
-  test:
-    name: Test on ${{ matrix.os }}
+  build-and-test:
+    name: ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
 
     strategy:
@@ -18,69 +17,24 @@ jobs:
           - os: ubuntu-latest
             name: Linux
           - os: macos-latest
-            name: macOS ARM
-          - os: windows-latest
-            name: Windows
+            name: macOS
 
     steps:
-      - name: Checkout code
+      - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup CMake
-        uses: jwlawson/actions-setup-cmake@v2
-        with:
-          cmake-version: "3.20"
-
-      - name: Setup MSVC environment (Windows)
-        if: runner.os == 'Windows'
-        uses: ilammy/msvc-dev-cmd@v1
-
-      - name: Install Ninja (Windows)
-        if: runner.os == 'Windows'
-        uses: seanmiddleditch/gha-setup-ninja@v3
-
-      - name: Configure CMake (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          New-Item -ItemType Directory -Force -Path build
-          cd build
-          # Remove MinGW from PATH to force MSVC detection
-          $env:Path = ($env:Path -split ';' | Where-Object { $_ -notlike '*mingw*' }) -join ';'
-          cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=cl -DCMAKE_CXX_COMPILER=cl
-        shell: pwsh
-
-      - name: Configure CMake (Unix)
-        if: runner.os != 'Windows'
+      - name: Configure
         run: |
           mkdir -p build
           cd build
           cmake ..
-        shell: bash
 
-      - name: Build tests (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          cd build
-          cmake --build . --target RocketSimTests -j4
-        shell: pwsh
-
-      - name: Build tests (Unix)
-        if: runner.os != 'Windows'
+      - name: Build
         run: |
           cd build
           cmake --build . --target RocketSimTests -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)
-        shell: bash
-
-      - name: Run tests (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          cd build
-          ctest --output-on-failure
-        shell: pwsh
 
-      - name: Run tests (Unix)
-        if: runner.os != 'Windows'
+      - name: Test
         run: |
           cd build
           ctest --output-on-failure
-        shell: bash
diff --git a/.gitignore b/.gitignore
@@ -50,4 +50,14 @@ CMakeSettings.json
 ___*
 
 # MacOS
-.DS_Store
+.DS_Store
+
+# python
+python/build/
+python/dist/
+python/RocketSim.egg-info/
+python/.scikit-build/
+python/.venv/
+python/.pytest_cache/
+__pycache__/
+*.pyc
diff --git a/README.md b/README.md
@@ -1,68 +1,63 @@
-![image](https://user-images.githubusercontent.com/36944229/219303954-7267bce1-b7c5-4f15-881c-b9545512e65b.png)
+# RocketSimPy
 
-**A C++ library for simulating Rocket League games at maximum efficiency**
+**A modernized fork of [RocketSim](https://github.com/ZealanL/RocketSim) with official Python bindings**
 
-RocketSim is a complete simulation of Rocket League's gameplay logic and physics that is completely standalone.
-RocketSim supports the game modes: Soccar, Hoops, Heatseeker, and Snowday.
+A C++ library for simulating Rocket League games at maximum efficiency, now with first-class Python support via [nanobind](https://github.com/wjakob/nanobind).
 
-# Speed
-RocketSim is designed to run extremely fast, even when complex collisions and suspension calculations are happening every tick.
-On an average PC running a single thread of RocketSim with two cars, RocketSim can simulate around 20 minutes of game time every second.
-This means that with 12 threads running RocketSim, you can simulate around 10 days of game time every minute!
+## What's Different
 
-# Accuracy
-RocketSim is not a perfectly accurate replication of Rocket League, but is close enough for most applications (such as training ML bots).
-RocketSim is accurate enough to:
-- *Train machine learning bots to SSL level (and probably beyond)*
-- *Simulate different shots on the ball at different angles to find the best input combination*
-- *Simulate air control to find the optimal orientation input*
-- *Simulate pinches*
+This fork builds on ZealanL's original RocketSim and takes inspiration from [mtheall's Python bindings](https://github.com/mtheall/RocketSim):
 
-However, the tiny errors will accumulate over time, so RocketSim is best suited for simulation with consistent feedback.
+- **nanobind bindings** — Faster, cleaner Python bindings (not pybind11)
+- **Full test coverage** — C++ and Python test suites with CI
+- **RLGym compatible** — Drop-in replacement for [rlgym](https://rlgym.org/) environments
+- **Modern build system** — scikit-build-core + uv for Python packaging
 
-## Installation
-- Clone this repo and build it
-- Use https://github.com/ZealanL/RLArenaCollisionDumper to dump all of Rocket League's arena collision meshes
-- Move those assets into RocketSim's executing directory
+## Quick Start
 
-## Documentation
-Documentation is available at: https://zealanl.github.io/RocketSimDocs/
+```bash
+# Build and install Python bindings
+cd python
+uv build --wheel
+uv pip install dist/*.whl
+```
+
+```python
+import RocketSim as rs
 
-## Bindings
-If you don't want to work in C++, here are some (unofficial) bindings written in other languages:
-- **Python**: https://github.com/mtheall/RocketSim by `mtheall`
-- **Python**: https://github.com/uservar/pyrocketsim by `uservar`
-- **Rust**: https://github.com/VirxEC/rocketsim-rs by `VirxEC`
+rs.init("collision_meshes")
+arena = rs.Arena(rs.GameMode.SOCCAR)
+car = arena.add_car(rs.Team.BLUE, rs.CAR_CONFIG_OCTANE)
+arena.step(100)
+```
 
-Official Python bindings are currently in the works.
+## Speed
 
-## Performance Details
-RocketSim already heavily outperforms the speed of Rocket League's physics tick step without optimization.
+RocketSim simulates ~20 minutes of game time per second on a single thread. With 12 threads, that's ~10 days of game time per minute.
 
-Version performance comparison:
-```
-OS: Windows 10 (Process Priority = Normal)
-CPU: Intel i5-11400 @ 2.60GHz
-Ram Speed: 3200MZ
-Compiler: MSVC 14.16
-=================================
-Arena: Default (Soccar)
-Cars: 2 on each team (2v2)
-Inputs: Randomly pre-generated, changed every 2-60 ticks for each car
-=================================
-Single-thread performance (calculated using average CPU cycles per tick on the RocketSim thread) (1M ticks simulated):
-v1.0.0 = 30,334tps
-v1.1.0 = 48,191tps
-v1.2.0 = 50,763tps
-v2.0.0 = ~50,000tps
-v2.1.0 = 114,481tps
-```
+## Accuracy
+
+Accurate enough to train ML bots to SSL level, simulate shots, air control, and pinches. Small errors accumulate over time — best suited for simulation with consistent feedback.
 
-## Issues & PRs
-Feel free to make issues and pull requests if you encounter any issues!
+## Installation
+
+1. Clone this repo
+2. Dump arena collision meshes using [RLArenaCollisionDumper](https://github.com/ZealanL/RLArenaCollisionDumper)
+3. Build: `mkdir build && cd build && cmake .. && make`
+
+For Python bindings, see [python/README.md](python/README.md).
+
+## Documentation
+
+- Original docs: [zealanl.github.io/RocketSimDocs](https://zealanl.github.io/RocketSimDocs/)
+- Python API: [python/README.md](python/README.md)
 
-You can also contact me on Discord if you have questions: `Zealan#5987`
+## Credits
+
+- [ZealanL/RocketSim](https://github.com/ZealanL/RocketSim) — Original implementation
+- [mtheall/RocketSim](https://github.com/mtheall/RocketSim) — Python bindings inspiration
+- [RLGym](https://rlgym.org/) — Target compatibility
 
 ## Legal Notice
-RocketSim was written to replicate Rocket League's game logic, but does not actually contain any code from the game.
-To Epic Games/Psyonix: If any of you guys have an issue with this, let me know on Discord and we can resolve it.
+
+RocketSim replicates Rocket League's game logic but contains no code from the game.
diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt
@@ -0,0 +1,61 @@
+cmake_minimum_required(VERSION 3.15...3.27)
+project(RocketSimPy LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Find Python and nanobind
+find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED)
+
+# Detect the installed nanobind package and import it into CMake
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
+find_package(nanobind CONFIG REQUIRED)
+
+# Collect RocketSim source files
+file(GLOB_RECURSE ROCKETSIM_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/../src/*.cpp"
+)
+
+# Collect all Bullet sources
+file(GLOB_RECURSE BULLET_SOURCES
+    "${CMAKE_CURRENT_SOURCE_DIR}/../libsrc/bullet3-3.24/*.cpp"
+)
+
+# Create the nanobind module
+nanobind_add_module(
+    RocketSim
+    STABLE_ABI
+    NB_STATIC
+    src/bindings.cpp
+    ${ROCKETSIM_SOURCES}
+    ${BULLET_SOURCES}
+)
+
+# Include directories
+target_include_directories(RocketSim PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/../src"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../libsrc/bullet3-3.24"
+)
+
+# Suppress warnings from Bullet library (third-party code)
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang|AppleClang")
+    target_compile_options(RocketSim PRIVATE
+        -Wno-c99-extensions
+        -Wno-gnu-statement-expression-from-macro-expansion
+        -Wno-unused-parameter
+        -Wno-sign-compare
+        -Wno-unused-variable
+        -Wno-unused-function
+        -Wno-unused-but-set-variable
+        -Wno-reorder-ctor
+        -Wno-deprecated-copy
+        -Wno-delete-non-abstract-non-virtual-dtor
+        -Wno-return-type
+    )
+endif()
+
+# Install the module
+install(TARGETS RocketSim LIBRARY DESTINATION .)
+