Buckets:

|
download
raw
5.57 kB
# Unity ML-Agents Environment
OpenEnv wrapper for [Unity ML-Agents](https://github.com/Unity-Technologies/ml-agents) environments.
## Supported Environments
| Environment | Action Type | Description |
|------------|-------------|-------------|
| **PushBlock** | Discrete (7) | Push a block to a goal position |
| **3DBall** | Continuous (2) | Balance a ball on a platform |
| **3DBallHard** | Continuous (2) | Harder version of 3DBall |
| **GridWorld** | Discrete (5) | Navigate a grid to find goals |
| **Basic** | Discrete (3) | Simple left/right movement |
More environments may be available depending on the ML-Agents registry version.
## Quick Start
Install the package from the OpenEnv repository and start a server:
```bash
cd envs/unity_env
uv sync # or: pip install -e .
uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
```
The first run downloads the Unity binaries (about 500 MB) to `~/.mlagents-cache/`. Run a single worker: Unity environments are not thread-safe.
```python
from unity_env import UnityAction, UnityEnv
with UnityEnv(base_url="http://localhost:8000").sync() as client:
result = client.reset(env_id="PushBlock")
print(f"Observation dims: {len(result.observation.vector_observations)}")
for _ in range(100):
result = client.step(UnityAction(discrete_actions=[1])) # move forward
print(f"Reward: {result.reward}, Done: {result.done}")
if result.done:
result = client.reset()
```
`reset(env_id=...)` switches environments, for example to `3DBall` with `UnityAction(continuous_actions=[0.5, -0.3])`.
### Without a separate server
`UnityEnv.from_direct()` starts a local server in a subprocess and returns a client connected to it:
```python
client = UnityEnv.from_direct(
env_id="PushBlock",
no_graphics=False, # show the Unity window
width=1280,
height=720,
time_scale=1.0, # 20.0 for fast training
quality_level=5, # 0-5
port=8765,
)
```
### Docker
```bash
cd envs/unity_env
docker build -f server/Dockerfile -t unity-env:latest .
docker run -p 8000:8000 -v ~/.mlagents-cache:/root/.mlagents-cache unity-env:latest
```
The image runs headless (`UNITY_NO_GRAPHICS=1`). The volume keeps the downloaded binaries between runs. To start the container from Python, use `UnityEnv.from_docker_image("unity-env:latest", env_vars={"UNITY_TIME_SCALE": "20"})`.
Docker mode doesn't work on Apple Silicon: the Unity binaries are x86_64 only and Unity's Mono runtime crashes under emulation (`Assertion: should not be reached at tramp-amd64.c`). Use the local server or `from_direct()`, which download native macOS binaries, or an x86_64 Linux machine.
### Example script
[`examples/unity_simple.py`](https://github.com/huggingface/OpenEnv/blob/main/examples/unity_simple.py) runs episodes in any of the three modes:
```bash
python examples/unity_simple.py --direct --env 3DBall --episodes 5
python examples/unity_simple.py --url http://localhost:8000
python examples/unity_simple.py --docker --no-graphics --time-scale 20
```
Other options: `--docker-image`, `--env` (`PushBlock`, `3DBall` or `both` to alternate), `--max-steps`, `--width`, `--height`, `--quality-level`, `--quiet`.
## Actions
**UnityAction** takes `discrete_actions` or `continuous_actions`, depending on the environment.
PushBlock (discrete): `0` no-op, `1` forward, `2` backward, `3` rotate left, `4` rotate right, `5` strafe left, `6` strafe right.
3DBall (continuous): two values in `[-1, 1]`, the X-axis and Z-axis rotation of the platform.
## Observations
**UnityObservation** has `vector_observations` (70 values for PushBlock, 8 for 3DBall), `behavior_name` and `action_spec_info`. Pass `include_visual=True` to `reset()` to also get `visual_observations` as base64-encoded PNG images, where the environment supports them.
`client.state()` returns `env_id`, `episode_id`, `step_count`, `available_envs`, `action_spec` and `observation_spec`.
## Reward
The reward is the ML-Agents environment's own reward for the first agent at each step.
## Configuration
Server environment variables (the `UnityMLAgentsEnvironment` constructor takes the same settings):
| Variable | Default | Description |
|----------|---------|-------------|
| `UNITY_ENV_ID` | `PushBlock` | Default Unity environment |
| `UNITY_NO_GRAPHICS` | `0` (`1` in the Docker image) | `1` for headless mode |
| `UNITY_WIDTH` | `1280` | Window width in pixels |
| `UNITY_HEIGHT` | `720` | Window height in pixels |
| `UNITY_TIME_SCALE` | `1.0` | Simulation speed multiplier |
| `UNITY_QUALITY_LEVEL` | `5` | Graphics quality, 0-5 |
| `UNITY_CACHE_DIR` | `~/.mlagents-cache` | Binary cache directory |
| `UNITY_INCLUDE_VISUAL` | `0` | `1` to include camera images by default, e.g. so the `/web` playground shows them (needs graphics: `UNITY_NO_GRAPHICS=0`) |
## Limitations
- Binaries are platform-specific (macOS, Linux, Windows).
- Graphics mode needs a display (X11 on Linux).
- Only the first agent is used. Multi-agent environments are not supported yet.
- `mlagents-envs` is installed from the ML-Agents GitHub repository. To use a specific branch, clone [ml-agents](https://github.com/Unity-Technologies/ml-agents) and `pip install -e ./ml-agents-envs`.
## References
- [Unity ML-Agents documentation](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/index.html)
- [ML-Agents GitHub](https://github.com/Unity-Technologies/ml-agents)
- [Example environments](https://docs.unity3d.com/Packages/com.unity.ml-agents@4.0/manual/Learning-Environment-Examples.html)

Xet Storage Details

Size:
5.57 kB
·
Xet hash:
f51cd51f909c0b6694b4bc6dc09e7aaaa10d980bf70325ad6e2e094b435c0b7a

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.