> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SimForge Worlds and assets

> Download SimForge Worlds (the public maps) with simforge maps pull, fetch the actor models, and manage the local cache.

SimForge Worlds are where scenarios happen. Each World is an HD map of a real-world road network (lanes, signals, the traffic network) with its digital twin, the 3D environment the renderer draws. The CLI calls a World a map. Scenarios are built on an installed map, and the installed version is the one they pin.

## Download a map

```sh theme={null}
simforge maps pull easterbrook-discovery-school@v9 --accept-license
```

`maps pull` downloads a map your signed-in account is entitled to, checks the download against its sha256, and installs it into the local maps cache. Pin a version with `name@version`; without one you get the current release. `--accept-license` accepts the current agreement, as for the runtime. `--cache-root DIR` puts the cache somewhere else. An interrupted download resumes when you run the command again.

`--for` says what the map is for:

| `--for` | Installs | Enough for |
| - | - | - |
| `2d` (default) | the road network (OpenDRIVE, lanes, signals, typed locations), its 2D drawing, the ground and the static colliders: a 3–25 MB download | `scenario new` and `scenario apply`, `locations`, `simulate`, `render --mode 2d` |
| `3d` | the whole map, adding the meshes and textures the renderer draws: a 5–22 GB download | all of the above plus a local `render --mode 3d` |

Without `--for`, `maps pull` installs `2d`, unless the map is already installed for 3D: an update of a 3D install stays `3d`. A render with `--cloud` needs no local map at all: the cloud resolves the map the scenario names. So the usual local setup is the default 2D install for authoring and 2D renders, and `--cloud` for 3D. A local 3D render of a map installed for 2D only fails with `map_3d_not_installed`, which names the command that adds the rest: `simforge maps pull <name>@<version> --for 3d`.

Accepting the agreement is all a public map needs: the first download entitles your workspace. The public maps are `richmond-field-station`, `easterbrook-discovery-school`, `el-camino-road`, `belmont-research-center`, `yale-street`, `san-ramon-phase-1` and `di-rosa-sf`. A map that is not public fails with `entitlement_required` (pick another map; retrying does not help), and one an operator withdrew from your workspace with `entitlement_revoked`. Every map download is signed, and the CLI refuses an unsigned or untrusted one (`signature_*`).

`simforge maps list` and `simforge maps show <map>` give each map's exact sizes before you download: its `packs` list every variant with its `version`, `downloadBytes` and `installedBytes`. A `--for 3d` download is large. A pull that cannot fit is refused before it downloads anything (`disk_insufficient`, naming the free and required bytes); the download and its unpacking stay inside the cache folder. While it runs, the pull writes `distribution.download.progress` and then `distribution.extract.progress` events (JSON lines on stderr) at each tenth and at least every 30 seconds. Pulling a map again downloads it again, so pull each version once. After the download, commands take the map's name (`easterbrook-discovery-school`), not `name@version`.

```sh theme={null}
simforge maps status
```

`maps status` lists the maps in the local cache and what each is installed for (`installed`: `2d` or `3d`) without going online.

## Maps in the cloud

```sh theme={null}
simforge maps list
simforge maps show <map-id>
```

These list the hosted maps your workspace can use with `--cloud`, with their `packs` (sizes per variant); each row's `installed` says what of it is in the local cache (`2d`, `3d` or `null`). Signed out they list the public maps (`"catalogue": "public"`), so you can see what there is before you create an account.

## Actor models

```sh theme={null}
simforge assets pull
```

`assets pull` downloads the actor models the renderer draws (cars, people, props) and their `ATTRIBUTION.json`, checking every file's sha256. The public actor set is the CARLA asset library under CC BY 4.0: keep the attribution file with anything you publish that shows them.

## When a map is missing

A local command on a map that is not installed fails with `map_not_installed` and names the map. Pull it, then run the command again. `simforge doctor` shows the cache folders and their free space.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.