# OpenHUTB (hutb): a human and vehicle simulator built on Unreal Engine

> OpenHUTB, or hutb, is an MIT-licensed C++ simulator for embodied humans, ground vehicles, aircraft and underwater robots, distributed as a Windows downloader plus a Python API. It is a fork-line of the CARLA-style stack, and the documentation is mostly Chinese.

**OpenHUTB/hutb** — 人车模拟器（Human-vehicle Simulator）

- Repository: https://github.com/OpenHUTB/hutb
- Website: OpenHUTB.github.io
- Stars: 621 · Forks: 453
- Language: C++
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/openhutb-hutb

## What OpenHUTB solves, and who is actually meant to use it

Most simulation stacks pick one subject. A driving simulator handles vehicles and maybe pedestrians as obstacles. A drone simulator handles rotors and aerodynamics. A humanoid simulator handles joints and contact. OpenHUTB, whose repository description reads "Human-vehicle Simulator", takes the opposite position: one Unreal Engine world that carries an embodied human, a ground vehicle, an air vehicle and a water vehicle at the same time. The README lists the targets explicitly as 具身人 (embodied human), 地面载具 (ground vehicle), 空域载具 (air vehicle) and 水域载具 (water vehicle), and calls the whole thing a film-grade physics simulator aimed at accelerating algorithm development, training and validation for humans and robots.

The intended audience is narrower than that sentence suggests. The README's hardware section asks for an Intel i7 9th to 11th generation or i9 9th to 11th generation, or an AMD Ryzen 7 or Ryzen 9, at least 16 GB of RAM, an NVIDIA RTX 2070 or better, and Windows 10+, Ubuntu 18.04+ or macOS 12+. That is a workstation requirement, not a laptop requirement. The second audience is artists: the README notes that art staff can skip compilation entirely and unpack software/hutb/hutb_editor.zip to launch an Unreal editor with the plugins already in place. The third audience is reinforcement learning and autonomous driving researchers who want a Python control surface rather than a C++ one, which is why the primary examples are Python scripts.

## How the simulator is put together: Unreal, LibCarla, PythonAPI and the plugin repositories

The repository layout tells most of the story. Unreal/ holds the engine-side project, LibCarla/ holds the C++ client library, PythonAPI/ holds the Python bindings and example scripts, Co-Simulation/ and osm-world-renderer/ sit alongside them, and Util/BuildTools/ holds the platform makefiles that the top-level Makefile includes. On Windows the makefile layer resolves to Util/BuildTools/Windows.mk, otherwise to Util/BuildTools/Linux.mk, which is how a single Makefile drives both platforms.

The Python side is not a thin wrapper. The README's install path puts a wheel under hutb/PythonAPI/carla/dist/ and has you install it with pip, and it states that the package supports Python 3.7 through 3.14. That range is wider than most simulation bindings, and it is the part most likely to break in practice, because a wheel built for one interpreter ABI will not install on another. The examples directory carries the scripts that matter: generate_traffic.py for populating a scene, manual_control.py for driving a pedestrian with a filter argument, and util/config.py for switching the map and the game mode.

Mode switching is the design decision worth noticing. The README says that from v2.3.0 onward the build supports Carla mode and AirSim mode at the same time, and that you select between them through a map option rather than by launching a different binary. The VR cockpit is reached the same way. That keeps one binary and one asset set, at the cost of making the map string carry configuration that would otherwise live in a config file.

## Installing OpenHUTB and running a first traffic scene

The README does not ask you to build anything for a first run. It points at a downloader executable, and the simulator lands in a directory you then work inside. Note that the downloader link in the README is a Gitee release asset, and the README does not document a checksum or a signature for it.

```bash
# Step 1: run the downloader from the README link, then change into the generated tree
cd hutb/PythonAPI/carla/dist/
```

Inside that directory you install the wheel that matches your interpreter. The README gives the glob form and states support for Python 3.7 to 3.14.

```bash
pip install hutb-*.whl
```

With the package installed, the first meaningful run is a traffic scene. The README points at generate_traffic.py as the example that spawns vehicles and pedestrians.

```bash
python PythonAPI/examples/generate_traffic.py
```

If you want to control a pedestrian yourself, the README's example passes a filter argument rather than a vehicle id.

```bash
python PythonAPI/examples/manual_control.py --filter walker.pedestrian.*
```

Switching modes goes through config.py, not through a separate launcher. The README shows the VR cockpit as a map option with GAME=VR, and the drone mode as GAME=AIR. After takeoff, the README says pressing Enter cycles through states.

```bash
python config.py --map Town10HD?GAME=VR
python config.py --map Town10HD?GAME=AIR
python PythonClient/multirotor/hello_drone.py
```

For source builds the README gives two setup.bat invocations and nothing more: setup.bat -l to start the editor, setup.bat -p to package. The hutb branch is described as carrying the newest version together with the newest fixes and features, so a clone of the default branch is not the same artifact as a tagged release.

## The build story is the weakest part of the documentation

The README offers setup.bat -l and setup.bat -p and then defers to two documentation pages, one for Windows and one for Linux. That is a thin surface for a project whose Unreal/ directory implies a full engine build, and the repository root backs up the impression: there is a Jenkinsfile, a Jenkinsfile_linux, a BuildWindows.ps1, a Makefile that includes platform makefiles, and a wheel_config.ini. Those are the artifacts of a build that has real configuration, and none of them are explained in the README.

There is no rollback procedure described anywhere in the README. If a mode switch or a wheel install leaves your environment in a bad state, the README does not tell you how to get back. There is also no stated compatibility matrix for the ecosystem repositories it links, which include Scenario Runner, ROS-bridge, driving-benchmarks, the AutoWare bridge and a separate Apollo bridge repository. Those are named as related repositories, not as tested pairings, and the README does not claim they work against a specific hutb release.

The macOS situation deserves a direct note. macOS 12+ appears in the hardware requirements, but the build instructions the README links to are titled for Windows and for Linux. If you are on macOS, the README gives you a supported platform line and no corresponding build page.

## When OpenHUTB is the wrong tool

If your work is single-domain and you already know your simulator, OpenHUTB's breadth is a cost rather than a feature. A team doing pure multirotor control gets rotor dynamics from a dedicated flight simulator and pays for it with a smaller asset pipeline; a team doing pure autonomous driving gets a narrower, more heavily documented stack. Here you carry an Unreal Engine project, a wheel whose Python range spans 3.7 to 3.14, and a map-string convention for mode selection, in exchange for having pedestrians, cars, drones and underwater robots in one world.

The second wrong-tool case is documentation language. The README is Simplified Chinese, and the English entry point is a separate README_EN.md file. Several of the linked pages are Chinese-only, including the VR cockpit page and the air documentation. If your team cannot read Chinese, you are working from a partial translation and from the repository layout itself.

The third case is hardware. An RTX 2070 floor with 16 GB of RAM means cloud instances and CI runners need a GPU class that is not the default. Running the simulator headless in a pipeline is not something the README describes.

## How it differs from CARLA and from AirSim

The honest comparison is with the two projects OpenHUTB borrows from. CARLA is the reference point for the driving side: it is the simulator behind the leaderboard the README links, and OpenHUTB reuses its Python API shape, its PythonAPI/examples layout and its PythonAPI/util/config.py entry point. The difference in approach is scope. CARLA's subject is driving, with pedestrians as actors inside a driving scene. OpenHUTB's stated subject is the human and the vehicle together, across ground, air and water, which is why the air plugin and the MuJoCo underwater plugin are separate repositories in its ecosystem rather than optional extras.

AirSim is the reference point for the flight side, and the README's own description of v2.3.0 is that Carla mode and AirSim mode are both supported by default and selected through the map string. That is a different integration strategy from running two simulators side by side: the mode is a runtime property of the loaded map. The trade-off is that anything you learn about mode selection is specific to this project, because the mechanism is a query parameter on a map name.

Against both, the distinguishing asset is the content. The README lists freely usable town layouts, buildings, vehicles, pedestrians and props created for this purpose, with catalogue pages for each. That is the part neither of the upstream projects gives you in the same form.

## Maintenance, licensing and what an upgrade costs you

The repository is not archived, and its last push was on 2026-09-08. The release cadence visible in the release list is uneven: v2.2 was tagged on 2025-07-21, v2.3 on 2026-06-25, and v2.10.0 on 2026-07-07. The last two are twelve days apart, which suggests the project tags more often than the gaps between v2.2 and v2.3 would imply. v2.10.0 is described as a unified simulation of embodied humans, drones and unmanned vehicles. v2.3 is described as air-ground integration. v2.2 is described as synchronized to 0.9.16, which points at an upstream version the fork tracks.

Upgrade cost is dominated by two things. First, the wheel: it is installed by glob from hutb/PythonAPI/carla/dist/, and the README states the supported Python range as 3.7 to 3.14. A release that changes the built interpreter set means reinstalling, and nothing in the README describes a side-by-side install. Second, the map-string mode convention. A script that hardcodes Town10HD?GAME=VR or Town10HD?GAME=AIR is coupled to both the map name and the mode token, and the README does not describe a stable alias for either.

The licence is MIT, per the repository metadata and the badge in the README. MIT is permissive, so redistribution and commercial use are not restricted by the licence text itself. That said, the simulator embeds Unreal Engine and ships digital assets, and the README does not state the licence terms for the asset packs or for the engine. Check those separately before shipping anything built on this, and treat that as a question for your own counsel rather than something the README answers. The requirements.txt at the repository root is documentation tooling, not runtime dependencies: it lists python-markdown-math, imageio and pymdown-extensions.

## Conclusion

Adopt OpenHUTB if you need one Unreal Engine scene graph that carries pedestrians, ground vehicles, drones and underwater robots, and you are comfortable reading Chinese documentation and running either Windows or Ubuntu with an RTX 2070-class GPU. Do not adopt it if you need English-only documentation, a fully reproducible Linux build from source, or a simulator with a published compatibility matrix for ROS 2 and Apollo bridges. Before committing, verify three things: that the wheel in hutb/PythonAPI/carla/dist/ installs against your Python version, that config.py --map Town10HD?GAME=VR reaches the VR cockpit on your hardware, and that the hutb branch builds with setup.bat -p on your toolchain.

## FAQ

### How do I install OpenHUTB (hutb) on Windows?

The README's path is to download and run the simulator downloader executable, then go into the generated hutb/PythonAPI/carla/dist/ directory and install the wheel with pip. The README states the package supports Python 3.7 to 3.14. Source builds are separate and use setup.bat.

### What Python versions does the OpenHUTB wheel support?

The README states support for Python 3.7 through 3.14, and the install step is pip install hutb-*.whl from hutb/PythonAPI/carla/dist/. The README does not list which interpreter each wheel in that directory was built for.

### How do I switch OpenHUTB between VR cockpit, Carla and AirSim modes?

The README uses PythonAPI/util/config.py with a map option: python config.py --map Town10HD?GAME=VR for the VR cockpit and python config.py --map Town10HD?GAME=AIR for drone mode. It notes that from v2.3.0 the build supports Carla mode and AirSim mode at the same time.

### What hardware does OpenHUTB require?

The README lists an Intel i7 9th to 11th generation or i9 9th to 11th generation, or an AMD Ryzen 7 or Ryzen 9, at least 16 GB of RAM, an NVIDIA RTX 2070 or better, and Windows 10+, Ubuntu 18.04+ or macOS 12+. The build instructions the README links are titled for Windows and Linux only.

## Sources

- [Issues](https://github.com/OpenHUTB/hutb/issues)
- [License: MIT](https://github.com/OpenHUTB/hutb/blob/hutb/LICENSE)
- [OpenHUTB/hutb on GitHub](https://github.com/OpenHUTB/hutb)
- [README](https://github.com/OpenHUTB/hutb/blob/hutb/README.md)
- [Releases](https://github.com/OpenHUTB/hutb/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openhutb-hutb