{"id":13699532,"url":"https://github.com/alex-petrenko/megaverse","last_synced_at":"2026-04-02T21:04:26.666Z","repository":{"id":41197017,"uuid":"274845524","full_name":"alex-petrenko/megaverse","owner":"alex-petrenko","description":"High-throughput simulation platform for Artificial Intelligence reseach","archived":false,"fork":false,"pushed_at":"2022-12-01T03:09:37.000Z","size":15935,"stargazers_count":219,"open_issues_count":4,"forks_count":20,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-08-02T20:04:33.160Z","etag":null,"topics":["3d","artificial-intelligence","games","reinforcement-learning","simulation"],"latest_commit_sha":null,"homepage":"https://www.megaverse.info","language":"C++","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/alex-petrenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-25T06:33:31.000Z","updated_at":"2024-07-08T14:41:34.000Z","dependencies_parsed_at":"2023-01-23T12:00:10.699Z","dependency_job_id":null,"html_url":"https://github.com/alex-petrenko/megaverse","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-petrenko%2Fmegaverse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-petrenko%2Fmegaverse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-petrenko%2Fmegaverse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alex-petrenko%2Fmegaverse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alex-petrenko","download_url":"https://codeload.github.com/alex-petrenko/megaverse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224398825,"owners_count":17304661,"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":["3d","artificial-intelligence","games","reinforcement-learning","simulation"],"created_at":"2024-08-02T20:00:35.719Z","updated_at":"2026-04-02T21:04:26.629Z","avatar_url":"https://github.com/alex-petrenko.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# Megaverse\n\n[\u003cimg src=\"https://img.shields.io/discord/987232982798598164?label=discord\"\u003e](https://discord.gg/4ZNdhfaZtK)\n\nMegaverse is a dedicated high-throughput rendering and simulation engine for Artificial Intelligence research.\nIt features an optimized batched renderer that enables generation of up to 1,000,000 observations per second on a single machine.\n\n* **Website:** [www.megaverse.info](https://www.megaverse.info) \n* **arXiv:** [arxiv.org/abs/2107.08170](https://arxiv.org/abs/2107.08170)\n\nLeft: RL agent completing a TowerBuilding task. Right: human player solving a randomly generated obstacle course.\n\n\u003cp align=\"middle\"\u003e\n\u003cimg src=\"https://github.com/alex-petrenko/megaverse/blob/master/data/tower_rl.gif?raw=true\" width=\"400\"\u003e\n\u003cimg src=\"https://github.com/alex-petrenko/megaverse/blob/master/data/obstacles_hard_play_x2.gif?raw=true\" width=\"400\"\u003e\n\u003c/p\u003e \n\n## Installation\n\nCurrently, the easiest way to install Megaverse is to build directly from sources.\n\n### Linux\n\n\n```shell\n# 0) A completely clean Linux installation needs basic OpenGL libraries. The rest of the dependencies are installed with Conda and don't require elevated privileges.\n$ sudo apt install libgl1-mesa-dev libegl1-mesa-dev\n\n# 1) Install VulkanSDK from https://vulkan.lunarg.com/sdk/home#linux (download and unzip), or use the following commands:\n$ wget https://sdk.lunarg.com/sdk/download/1.2.198.1/linux/vulkansdk-linux-x86_64-1.2.198.1.tar.gz\n$ mkdir vulkansdk \u0026\u0026 tar -xzf vulkansdk-linux-x86_64-1.2.198.1.tar.gz --directory vulkansdk\n\n# 2) Add Vulkan SDK binaries to PATH (might need to do it each time recompiling Megaverse is required):\n$ cd vulkansdk/1.2.198.1\n$ source ./setup-env.sh\n\n# 3) Clone the repo\n$ git clone https://github.com/alex-petrenko/megaverse.git\n\n# 4) Init submodules\n$ cd megaverse \n$ git submodule update --init --recursive\n\n# 5) Create a conda environment and install dependencies\n$ conda create --name megaverse python=3.9\n$ conda activate megaverse\n(megaverse) $ conda install -c conda-forge 'opencv\u003e=4.4,\u003c4.5' 'cmake\u003e=3.13' bullet cudatoolkit cudatoolkit-dev sdl2\n\n# (alternatively you can boostrap from an environment file: conda env create -f environment.yml)\n\n# 6) Install megaverse into a conda env\n(megaverse) $ python setup.py develop\n(megaverse) $ pip install -e .\n\n# (Optional) 6.1) Build a .whl file to be installed elsewhere\n(megaverse) $ python setup.py bdist_wheel\n```\n\n### macOS\n\nAlthough Vulkan-powered batched rendering is not supported on macOS, a limited OpenGL version can be built for\nlocal debugging and small-scale experiments on macOS.\nInstalling on mac is very similar to Linux, sans any Vulkan/CUDA dependencies.\n\n```shell\n# 1) Clone the repo\n$ git clone https://github.com/alex-petrenko/megaverse.git\n\n# 2) Init submodules\n$ cd megaverse \n$ git submodule update --init --recursive\n\n# 3) Create a conda environment and install dependencies\n$ conda create --name megaverse python=3.9\n$ conda activate megaverse\n(megaverse) $ conda install -c conda-forge 'opencv\u003e=4.4,\u003c4.5' 'cmake\u003e=3.13' bullet\n\n# 4) Install megaverse into a conda env\n(megaverse) $ python setup.py develop\n(megaverse) $ pip install -e .\n\n# (Optional) 4.1) Build a .whl file to be installed elsewhere\n(megaverse) $ python setup.py bdist_wheel\n```\n\n### Docker \n\nSince installation does not require elevated priviliges, Docker setup is not required.\nHowever, Docker-based installation is also available, see here:\n[docker/README.md](https://github.com/alex-petrenko/megaverse/blob/master/docker/README.md).\n\n## Examples\n\n### Python API\n\nThe following script executes a random policy:\n\n```Python\nimport numpy as np\nfrom megaverse.megaverse_env import MegaverseEnv\n\n\nenv = MegaverseEnv(\n    'TowerBuilding',\n    num_envs=2, num_agents_per_env=2,\n    num_simulation_threads=4, use_vulkan=True,\n    params={},\n)\nenv.reset()\n\nwhile True:\n    actions = [env.action_space.sample() for _ in range(env.num_agents)]\n    obs, rewards, dones, infos = env.step(actions)\n    if np.any(dones):\n        break\n\n    env.render()\n\n```\n\n## RL Training\n\nExample training script using Sample Factory RL framework. First install the prerequisite:\n\n```\npip install \"sample-factory\u003e=2.0\"\n```\n\n(this instruction was tested on version from branch `sf2`, commit f4b5e971f467fc8dcabc0adee8b1c04885412fbb,\n`pip install git+https://github.com/alex-petrenko/sample-factory.git@f4b5e971f467fc8dcabc0adee8b1c04885412fbb`)\n\nThen, to train agents in the TowerBuilding environment, execute:\n```\npython -m megaverse_rl.train_megaverse --train_for_seconds=360000000 --train_for_env_steps=2000000000 --algo=APPO --gamma=0.997 --use_rnn=True --rnn_num_layers=2 --num_workers=8 --num_envs_per_worker=2 --num_epochs=1 --rollout=32 --recurrence=32 --batch_size=4096 --actor_worker_gpus 0 --num_policies=1 --with_pbt=False --max_grad_norm=0.0 --exploration_loss=symmetric_kl --exploration_loss_coeff=0.001 --megaverse_num_simulation_threads=1 --megaverse_num_envs_per_instance=48 --megaverse_num_agents_per_env=1 --megaverse_use_vulkan=True --policy_workers_per_policy=2 --reward_clip=30 --env=TowerBuilding --experiment=TowerBuilding\n```\n\nObserve the behavior of agents by running:\n\n```\npython -m megaverse_rl.enjoy --algo=APPO --env=TowerBuilding --experiment=TowerBuilding --megaverse_num_envs_per_instance=1 --fps=20 --megaverse_use_vulkan=True\n```\n\nSee Sample Factory 2 documentation for additional information.\n\n## Development\n\n### Setting up a CMake project in IDE\n\nThe core functionality of Megaverse is implemented in C++ and uses CMake build system.\nThe easiest way to work on Megaverse C++ codebase is to use an IDE that can import a CMake project (defined by the root CMakeLists.txt in megaverse/src).\nAny such IDE would need to run `cmake` in order to build and debug the code.\nThus `cmake` needs to be able to find all the libraries installed through conda (such as Bullet and OpenCV).\n\nThe most straightforward way to make sure that libraries can be found is to start IDE directly from the conda environment we defined above (see section Installation/Linux).\nSpecifically, for CLion IDE it would look like this:\n\n```shell\n$ conda activate megaverse\n# navigate to Vulkan SDK installation dir\n(megaverse) $ cd vulkansdk-linux-x86_64-1.2.198.1/1.2.198.1/\n# make sure that Vulkan env variables are initialized\n(megaverse) $ source ./setup-env.sh\n# start the IDE from the terminal (assuming clion is in PATH, usually you can do this with Tools-\u003eCreate Command-Line Launcher)\n(megaverse) $ clion \u0026 \n```\n\nNow in the IDE open megaverse/src/CMakeLists.txt as CMake project and you should be able to build and run targets.\n\n#### Running an IDE without Conda enviroment\n\nAlternatively, if IDE is not run from a conda environment we might need to explicitly specify paths to libraries in IDE's CMake command line\n(i.e. in CLion that would be `Settings -\u003e Build,Execution,Deployment -\u003e CMake -\u003e CMake options`).\nYour CMake options might looks like this:\n\n```\n-DPYTHON_EXECUTABLE=/home/\u003cuser\u003e/miniconda3/envs/megaverse/bin/python\n-DCMAKE_CUDA_COMPILER=/home/\u003cuser\u003e/miniconda3/envs/megaverse/bin/nvcc\n-DOpenCV_DIR=/home/\u003cuser\u003e/miniconda3/envs/megaverse/lib/cmake/opencv4\n-DBUILD_GUI_APPS=ON\n```\n\nAdditionally, an environment variable `VULKAN_SDK=/home/\u003cuser\u003e/all/libs/vulkansdk-linux-x86_64-1.2.198.1/1.2.198.1/x86_64` must be set.\nIn most IDEs this can be set in the same CMake configuration dialogue.\n\nFinally, CMake should be able to find Bullet physics library. There are three ways to accomplish this:\n1. Install `libbullet-dev` and CMake will find the system-wide installation\n2. To link against `bullet` installed by Conda you need to make sure your IDE also uses Conda's `cmake`,\nrather than `cmake` bundled with the IDE. In CLion you can change this in `Settings -\u003e Build,Execution,Deployment -\u003e Toolchains -\u003e CMake`.\nThis way `cmake` should be able to find Conda's Bullet CMake config `\u003cenv\u003e/lib/cmake/bullet/BulletConfig.cmake`\n3. Alternatively, you can build Bullet from sources and add a CMake option `-DBULLET_ROOT` pointing to the correct location.\n\n### Notable build targets\n\nCMakeLists.txt defines many targets. The following targets are the most useful: \n\n* `megaverse` builds the overall project and the Python bindings (see setup.py)\n* `run_unit_tests` runs Google Tests (see `megaverse/src/test`)\n* `viewer_app` builds an interactive application that allows you to control agents with keyboard and explore environments with an overview camera.\nThis one is really designed to interact with a single environment at a time, and is very useful during development and debugging phase. See details below.\n* `megaverse_test_app` can use the parallel simulation engine and batch renderer to execute many environment at once. See details below.\n\n### Using viewer_app\n\n`viewer_app` can run any scenario in an interactive mode and offers a bunch of command line parameters:\n```\nUsage: viewer_app [options] \n\nOptional arguments:\n-h --help           \tshows help message and exits [default: false]\n-v --version        \tprints version information and exits [default: false]\n-l --list_scenarios \tlist registered scenario names [default: false]\n--scenario          \tname of the scenario to run [default: \"ObstaclesEasy\"]\n--num_agents        \tsize of the team, pass value 1 to have just a single agent [default: 2]\n--desired_fps       \trendering framerate for human perception; RL agents percieve the world at 15 FPS to avoid frameskip, hence the default value. [default: 15]\n--use_opengl        \tWhether to use OpenGL renderer instead of fast Vulkan renderer (currently Vulkan is only supported in Linux) [default: false]\n```\n\nOnce the app started, use keyboard to control the agent and the camera:\n* `WASD` and arrow keys to control the agent\n* `1,2,3,4,etc.` to switch between agents (if several are present in the environment)\n* Press `O` to toggle the overview camera, use mouse to control view angle\n* Use `UHJK` keys to control the position of the camera in the overview mode\n* Press `R` to reset the episode\n* Press `ENTER` to toggle Bullet collision debug view (only OpenGL version)\n* `ESC` to exit the app\n\n### Using megaverse_test_app\n\n`megaverse_test_app` uses parallel interface and is a much easier target to debug compared to Python Gym API. \n\n```\nusage: megaverse_test_app [options] \n\nThis app is designed to test the parallel execution engine and batched renderer\nby simulating multiple environments at once. This app uses pretty much the same interface\nas the Python Gym environment, sans the Python bindings. Whenever there is a problem\nwith the environment, it is much easier to debug this app directly, rather\nthan debugging the same code through Python.\n\nExample, render 12 agents at the same time:\nmegaverse_test_app --scenario Collect --visualize --num_envs 4 --num_simulation_threads 1 --num_agents 3 --hires\n\nSome performance figures for future reference (on 10-core Intel i9):\nmegaverse_test_app --scenario Empty --performance_test --num_envs 64 --num_simulation_threads 1 --num_agents 1\nyields approximately 75000 FPS\nmegaverse_test_app --scenario Collect --performance_test --num_envs 64 --num_simulation_threads 1 --num_agents 1\nyields approximately 27000 FPS\n\n\nOptional arguments:\n-h --help                \tshows help message and exits [default: false]\n-v --version             \tprints version information and exits [default: false]\n-l --list_scenarios      \tlist registered scenario names [default: false]\n--scenario               \tname of the scenario to run [default: \"ObstaclesEasy\"]\n--num_agents             \tsize of the team [default: 2]\n--use_opengl             \tWhether to use OpenGL renderer instead of fast Vulkan renderer (currently Vulkan is only supported in Linux) [default: false]\n--num_envs               \tnumber of parallel environments to simulate [default: 64]\n--num_simulation_threads \tnumber of parallel CPU threads to use for Bullet [default: 1]\n--visualize              \tWhether to render multiple environments on screen [default: false]\n--visualize              \tWhether to render multiple environments on screen [default: false]\n--delay_ms               \tDelay between rendered frames in milliseconds. Use only with --visualize [default: 1]\n--performance_test       \tRun for a limited number of env frames (currently 200000) to test performance. Uses random actions. [default: false]\n--hires                  \tRender at high resolution. Only use this parameter with --visualize and if the total number of agents is small [default: false]\n--user_actions           \tAllows the user to control agents (otherwise will use randomly generated actions). Use only with --visualize [default: false]\n```\n\n## Troubleshooting\n\n* A crash (segfault) on startup can be caused by the incorrect initialization of Vulkan device interface. Possible fixes:\n    * `sudo apt remove mesa-vulkan-drivers` (unless other packages you require depend on this package)\n    * Set envvar `export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json`, point to the location of `nvidia_icd.json` in your system.\n\n## Citation\n\nIf you use this repository in your work or otherwise wish to cite it, please make reference to our ICML2021 paper.\n\n```\n@inproceedings{petrenko2021megaverse,\n  title={Megaverse: Simulating Embodied Agents at One Million Experiences per Second},\n  author={Petrenko, Aleksei and Wijmans, Erik and Shacklett, Brennan and Koltun, Vladlen},\n  booktitle={ICML},\n  year={2021}\n}\n```\n\nFor questions, issues, inquiries please email apetrenko1991@gmail.com. \nGithub issues and pull requests are welcome.\n\n\n\n\n\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-petrenko%2Fmegaverse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex-petrenko%2Fmegaverse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-petrenko%2Fmegaverse/lists"}