{"id":13496487,"url":"https://github.com/BeamNG/BeamNGpy","last_synced_at":"2025-03-28T18:32:10.919Z","repository":{"id":37413112,"uuid":"139009770","full_name":"BeamNG/BeamNGpy","owner":"BeamNG","description":"Python API for BeamNG.tech","archived":false,"fork":false,"pushed_at":"2025-03-27T11:09:41.000Z","size":120232,"stargazers_count":279,"open_issues_count":42,"forks_count":48,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-27T12:25:07.686Z","etag":null,"topics":["ai","autonomous-driving","autonomous-vehicles","beamng","driving","python","simulator","simulator-api"],"latest_commit_sha":null,"homepage":"https://beamng.tech","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BeamNG.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":"contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-28T11:35:18.000Z","updated_at":"2025-03-25T18:13:32.000Z","dependencies_parsed_at":"2023-12-21T12:58:09.127Z","dependency_job_id":"4f9b8a5a-9a5e-4488-9e00-adee9957ca0e","html_url":"https://github.com/BeamNG/BeamNGpy","commit_stats":{"total_commits":673,"total_committers":23,"mean_commits":29.26086956521739,"dds":0.6686478454680536,"last_synced_commit":"2b6c38c6ff4b503ed0c97197e0e291cf0989c46e"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeamNG%2FBeamNGpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeamNG%2FBeamNGpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeamNG%2FBeamNGpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeamNG%2FBeamNGpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BeamNG","download_url":"https://codeload.github.com/BeamNG/BeamNGpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245844062,"owners_count":20681631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","autonomous-driving","autonomous-vehicles","beamng","driving","python","simulator","simulator-api"],"created_at":"2024-07-31T19:01:48.880Z","updated_at":"2025-03-28T18:32:05.910Z","avatar_url":"https://github.com/BeamNG.png","language":"Python","funding_links":[],"categories":["Python","Simulation Platforms"],"sub_categories":[],"readme":"# BeamNGpy\n\u003ca href=\"https://beamngpy.readthedocs.io/en/latest/\"\u003e\u003cimg src=\"https://github.com/BeamNG/BeamNGpy/raw/master/media/documentation.png\" /\u003e\u003c/a\u003e\n\n**BeamNGpy** is an official library providing a Python API to [BeamNG.tech][11],\nthe academia- and industry-oriented fork of the video game [BeamNG.drive][4].\nBeamNGpy and BeamNG.tech are designed to go hand in hand, both being kept up\nto date to support each other's functions, meaning using the latest versions\nof both is recommended.\n\nIt allows remote control of the simulation, including vehicles contained in it.\nSee [Features](#features) or go through the [Feature Overview][10] Jupyter notebook.\n\n## Table of Contents\n\n - [Features](#features)\n - [Prerequisites](#prereqs)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Compatibility](#compatibility)\n - [Troubleshooting](#troubleshooting)\n\n\u003ca name=\"features\"\u003e\u003c/a\u003e\n\n## Features\n\nBeamNGpy comes with a wide range of low-level functions to interact with the\nsimulation and a few higher-level interfaces that make more complex actions\neasier. Some features to highlight are:\n\n### Remote Control of Vehicles\n\nEach vehicle can be controlled individually and independently during the\nsimulation. This includes basic steering inputs, but also controls over\nvarious lights (headlights, indicators, etc.) or gear shifting.\n\n[Throttle Control.webm](https://user-images.githubusercontent.com/93574498/207164528-2415691f-3aee-478e-91ae-a1a53f733ee6.webm)\n\n[Steering Control.webm](https://user-images.githubusercontent.com/93574498/207164554-3f3d9478-3970-4c08-b1e3-2b656313ae33.webm)\n\n### AI-controlled Vehicles\n\nBesides manual control, BeamNG.tech ships with its own AI to control vehicles.\nThis AI can be configured and controlled from BeamNGpy. It can be used to\nmake a vehicle drive to a certain waypoint, make it follow another vehicle,\nspan the map, or follow a user-defined trajectory:\n\n![AI Trajectory](https://github.com/BeamNG/BeamNGpy/raw/master/media/ai_trajectory.png)\n\n### Dynamic Sensor Models\n\nVehicles and the environment can be equipped with various sensors that provide\nsimulated sensor data. These sensors include:\n\n - Cameras\n   - Color camera\n   - Depth camera\n   - Semantic and Instance annotations\n - Lidars\n - Inertial Measurement Units (IMU)\n - Ultrasonic Distance Measurements\n\n![Multiple cameras](https://github.com/BeamNG/BeamNGpy/raw/master/media/camera.png)\n![Lidar](https://github.com/BeamNG/BeamNGpy/raw/master/media/lidar.gif)\n\nThese sensors give perfect data from the simulation by default. Therefore, some\nof them, like the camera and lidar sensor, can be equipped to also simulate\nnoisy data.\n\n### Access to Road Network \u0026 Scenario Objects\n\nGeometry of roads in the currently-loaded level/scenario are made available\nvia BeamNGpy. Objects and vehicles that are currently active in the scene\nare also exposed, allowing for analysis of the current simulation state.\n\n![Road Network](https://github.com/BeamNG/BeamNGpy/raw/master/media/road_network.png)\n\n### Multiple Clients\n\nBeamNGpy interacts with BeamNG.tech as the client, with BeamNG.tech acting\nas the server. This allows for multiple BeamNGpy processes to connect to a\nrunning simulation and have each control the simulator, making it possible\nto, for example, [run a scenario in which each vehicle is controlled by\na separate client.](https://github.com/BeamNG/BeamNGpy/tree/master/examples/multi_client.ipynb)\n\n### More\n\nThere is a healthy collection of usage examples in the [examples/](https://github.com/BeamNG/BeamNGpy/tree/master/examples)\nfolder of this repository. These highlight more features, but also serve\nas documentation, so be sure to check them out.\n\n\u003ca name=\"prereqs\"\u003e\u003c/a\u003e\n\n## Prerequisites\n\nUsage of BeamNGpy requires BeamNG.tech to be installed. For commercial use,\ncontact us at [licensing@beamng.gmbh][3]. Builds of BeamNG.tech are made\navailable for research and academic use upon request using [this form][2].\nOnce downloaded, you can use the environment variable `BNG_HOME` to where\nBeamNG.tech can be run from, or provide a path to the BeamNGpy library\nduring initialization.\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\n\n## Installation\n\nThe library itself is available on [PyPI][5] and can therefore be installed\nusing common methods like `pip`:\n\n    pip install beamngpy\n\nIf you use [Anaconda](https://www.anaconda.com/products/distribution#download-section), you can\ninstall BeamNGpy from the `conda-forge` channel by:\n\n    conda install beamngpy -c conda-forge\n\nTo upgrade, use\n\n    pip install --upgrade beamngpy\n\nif you installed BeamNGpy using `pip` or\n\n    conda update beamngpy -c conda-forge --no-pin\n\nif you installed it using `conda`.\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n\n## Usage\n\n**DISCLAIMER:** If you are using an older version of `beamngpy` and BeamNG.tech, please follow the\ninstructions of the corresponding `README` file (for example, [1.27.1 instructions](https://github.com/BeamNG/BeamNGpy/tree/v1.27.1)). If you are using the latest version of BeamNGpy, continue following the instructions located in this README file.\n\nThe library can be imported using `import beamngpy`. A short\nusage example setting up a scenario with one vehicle in the West Coast USA map\nthat spans the area is:\n\n```python\nfrom beamngpy import BeamNGpy, Scenario, Vehicle\n\n# Instantiate BeamNGpy instance running the simulator from the given path,\n# communicating over localhost:64256\nbng = BeamNGpy('localhost', 64256, home='/path/to/bng/tech', user='/path/to/bng/tech/userfolder')\n# Launch BeamNG.tech\nbng.open()\n# Create a scenario in west_coast_usa called 'example'\nscenario = Scenario('west_coast_usa', 'example')\n# Create an ETK800 with the licence plate 'PYTHON'\nvehicle = Vehicle('ego_vehicle', model='etk800', license='PYTHON')\n# Add it to our scenario at this position and rotation\nscenario.add_vehicle(vehicle, pos=(-717, 101, 118), rot_quat=(0, 0, 0.3826834, 0.9238795))\n# Place files defining our scenario for the simulator to read\nscenario.make(bng)\n\n# Load and start our scenario\nbng.scenario.load(scenario)\nbng.scenario.start()\n# Make the vehicle's AI span the map\nvehicle.ai.set_mode('span')\ninput('Hit enter when done...')\n```\n\nWe have a [guide][6] helping you to get started and navigating our collection of examples and\nthe documentation of the library is available [here][7].\n\n## Compatibility\n\nBeamNG.tech is not a finished product but is still under development.\nThus frequent changes on the simulation side are to be expected.\nWhile 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.\nBelow is a list of compatible BeamNG.tech and BeamNGpy versions.\nHowever, we do not maintain minor versions: bug fixes and new features will only be available for the newest BeamNG.tech and BeamNGpy releases.\n\n| BeamNG.tech version | BeamNGpy version                                          |\n| ------------------- | --------------------------------------------------------- |\n| 0.33                | [1.30](https://github.com/BeamNG/BeamNGpy/tree/v1.30)     |\n| 0.32                | [1.29](https://github.com/BeamNG/BeamNGpy/tree/v1.29)     |\n| 0.31                | [1.28](https://github.com/BeamNG/BeamNGpy/tree/v1.28)     |\n| 0.30                | [1.27.1](https://github.com/BeamNG/BeamNGpy/tree/v1.27.1) |\n| 0.28, 0.29          | [1.26.1](https://github.com/BeamNG/BeamNGpy/tree/v1.26.1) |\n| 0.27                | [1.25.1](https://github.com/BeamNG/BeamNGpy/tree/v1.25.1) |\n| 0.26                | [1.24](https://github.com/BeamNG/BeamNGpy/tree/v1.24)     |\n| 0.25                | [1.23.1](https://github.com/BeamNG/BeamNGpy/tree/v1.23.1) |\n| 0.24                | [1.22](https://github.com/BeamNG/BeamNGpy/tree/v1.22)     |\n| 0.23                | [1.21.1](https://github.com/BeamNG/BeamNGpy/tree/v1.21.1) |\n| 0.22                | [1.20](https://github.com/BeamNG/BeamNGpy/tree/v1.20)     |\n| 0.21                | [1.19.1](https://github.com/BeamNG/BeamNGpy/tree/v1.19.1) |\n\n## Troubleshooting\n\nThis section lists common issues with BeamNGpy in particular. Since this\nlibrary is closely tied to BeamNG.tech and thus BeamNG.drive, it is also\nrecommended to consult the documentation on BeamNG.drive here:\n\n[https://documentation.beamng.com/][8]\n\n### BeamNGpy cannot establish a connection\n\n - Be sure to complete the initial set-up step described in the Usage section and to repeat it with every newly released BeamNG.tech version.\n - Make sure BeamNG.tech and Python are allowed to connect to your current\n   network in Windows Firewall.\n\n### BeamNG.tech quietly fails to launch\n\n- There is a known issue where BeamNG.tech quietly crashes when there is a\n  space in the configured userpath. Until this issue is fixed, it is\n  recommended to either switch to a path that does not contain a space or\n  change the userpath directly in the \"startup.ini\" file located in the\n  directory of your BeamNG.tech installation.\n\n## Contributions\n\nWe always welcome user contributions, be sure to check out our [contribution guidelines][9] first, before starting your work.\n\nThe Python code is formatted using [Black](https://github.com/psf/black), please use it to\nformat the code you want to contribute.\n\n[1]: https://beamngpy.readthedocs.io/en/latest/\n[2]: https://register.beamng.tech/\n[3]: mailto:licensing@beamng.gmbh\n[4]: https://store.steampowered.com/app/284160/BeamNGdrive/\n[5]: https://pypi.org/project/beamngpy/\n[6]: https://github.com/BeamNG/BeamNGpy/blob/master/examples/README.md\n[7]: https://beamngpy.readthedocs.io/en/latest/\n[8]: https://documentation.beamng.com/\n[9]: https://github.com/BeamNG/BeamNGpy/blob/master/contributing.md\n[10]: https://github.com/BeamNG/BeamNGpy/blob/master/examples/feature_overview.ipynb\n[11]: https://beamng.tech/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBeamNG%2FBeamNGpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBeamNG%2FBeamNGpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBeamNG%2FBeamNGpy/lists"}