# SimForge Worlds and assets

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

Source: https://simforge.ai/docs/maps

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
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
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
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
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.
