BeamNGpy is an official library providing a Python API to BeamNG.tech, the academia- and industry-oriented fork of the video game BeamNG.drive. BeamNGpy and BeamNG.tech are designed to go hand in hand, both being kept up to date to support each other's functions, meaning using the latest versions of both is recommended.
It allows remote control of the simulation, including vehicles contained in it. See Features or go through the Feature Overview Jupyter notebook.
BeamNGpy comes with a wide range of low-level functions to interact with the simulation and a few higher-level interfaces that make more complex actions easier. Some features to highlight are:
Each vehicle can be controlled individually and independently during the simulation. This includes basic steering inputs, but also controls over various lights (headlights, indicators, etc.) or gear shifting.
Besides manual control, BeamNG.tech ships with its own AI to control vehicles. This AI can be configured and controlled from BeamNGpy. It can be used to make a vehicle drive to a certain waypoint, make it follow another vehicle, span the map, or follow a user-defined trajectory:
Vehicles and the environment can be equipped with various sensors that provide simulated sensor data. These sensors include:
These sensors give perfect data from the simulation by default. Therefore, some of them, like the camera and lidar sensor, can be equipped to also simulate noisy data.
Geometry of roads in the currently-loaded level/scenario are made available via BeamNGpy. Objects and vehicles that are currently active in the scene are also exposed, allowing for analysis of the current simulation state.
BeamNGpy interacts with BeamNG.tech as the client, with BeamNG.tech acting as the server. This allows for multiple BeamNGpy processes to connect to a running simulation and have each control the simulator, making it possible to, for example, run a scenario in which each vehicle is controlled by a separate client.
There is a healthy collection of usage examples in the examples/ folder of this repository. These highlight more features, but also serve as documentation, so be sure to check them out.
Usage of BeamNGpy requires BeamNG.tech to be installed. For commercial use,
contact us at licensing@beamng.gmbh. Builds of BeamNG.tech are made
available for research and academic use upon request using this form.
Once downloaded, you can use the environment variable BNG_HOME to where
BeamNG.tech can be run from, or provide a path to the BeamNGpy library
during initialization.
The library itself is available on PyPI and can therefore be installed
using common methods like pip:
pip install beamngpy
If you use Anaconda, you can
install BeamNGpy from the conda-forge channel by:
conda install beamngpy -c conda-forge
To upgrade, use
pip install --upgrade beamngpy
if you installed BeamNGpy using pip or
conda update beamngpy -c conda-forge --no-pin
if you installed it using conda.
DISCLAIMER: If you are using an older version of beamngpy and BeamNG.tech, please follow the
instructions of the corresponding README file (for example, 1.27.1 instructions). If you are using the latest version of BeamNGpy, continue following the instructions located in this README file.
The library can be imported using import beamngpy. A short
usage example setting up a scenario with one vehicle in the West Coast USA map
that spans the area is:
from beamngpy import BeamNGpy, Scenario, Vehicle
# Instantiate BeamNGpy instance running the simulator from the given path,
# communicating over localhost:25252
bng = BeamNGpy('localhost', 25252, home='/path/to/bng/tech', user='/path/to/bng/tech/userfolder')
# Launch BeamNG.tech
bng.open()
# Create a scenario in west_coast_usa called 'example'
scenario = Scenario('west_coast_usa', 'example')
# Create an ETK800 with the licence plate 'PYTHON'
vehicle = Vehicle('ego_vehicle', model='etk800', license='PYTHON')
# Add it to our scenario at this position and rotation
scenario.add_vehicle(vehicle, pos=(-717, 101, 118), rot_quat=(0, 0, 0.3826834, 0.9238795))
# Place files defining our scenario for the simulator to read
scenario.make(bng)
# Load and start our scenario
bng.scenario.load(scenario)
bng.scenario.start()
# Make the vehicle's AI span the map
vehicle.ai.set_mode('traffic')
input('Hit Enter when done...')
# Disconnect BeamNG
bng.disconnect()
# Or close the simulator
# bng.close()
We have a guide helping you to get started and navigating our collection of examples and the documentation of the library is available here.
BeamNG.tech is also customizable with various command-line arguments. Check the documentation for reference.
BeamNG.tech is not a finished product but is still under development. Thus frequent changes on the simulation side are to be expected. While the BeamNGpy library maintains compatibility between minor versions for the user, this doesn't extend to the BeamNG.tech side. Not all BeamNGpy versions are compatible with all BeamNG.tech versions. Below is a list of compatible BeamNG.tech and BeamNGpy versions. However, we do not maintain minor versions: bug fixes and new features will only be available for the newest BeamNG.tech and BeamNGpy releases.
| BeamNG.tech version | BeamNGpy version |
|---|---|
| 0.34 | 1.31 |
| 0.33 | 1.30 |
| 0.32 | 1.29 |
| 0.31 | 1.28 |
| 0.30 | 1.27.1 |
| 0.28, 0.29 | 1.26.1 |
| 0.27 | 1.25.1 |
| 0.26 | 1.24 |
| 0.25 | 1.23.1 |
| 0.24 | 1.22 |
| 0.23 | 1.21.1 |
| 0.22 | 1.20 |
| 0.21 | 1.19.1 |
This section lists common issues with BeamNGpy in particular. Since this library is closely tied to BeamNG.tech and thus BeamNG.drive, it is also recommended to consult the documentation on BeamNG.drive here:
https://documentation.beamng.com/
We always welcome user contributions, be sure to check out our contribution guidelines first, before starting your work.
The Python code is formatted using Black, please use it to format the code you want to contribute.
FAQs
Python API to interact with BeamNG.tech.
We found that beamngpy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.