# City guide

Switch to **City** in the toolbar. The city is laid out from the repository's folder tree at human
scale, so a large repository is a large city.

## Reading the city

| You see | It means |
|---|---|
| A **district** (big block, name floating above its tallest tower) | A top-level folder |
| A **block** inside it, separated by streets | A nested folder; deeper folders have narrower streets |
| A **building** | A file |
| Building **footprint** | Lines of code |
| Building **height** | Complexity (branching) |
| **Lit windows** | Definitions: more functions and classes, more lights on |
| Building **colour** | Semantic layer (application, tests, vendor, …), switchable palette |
| Name on the **roof** and **wall** | The file name |
| **Green street sign** sticking out at a corner | The folder that block belongs to; each corner of an intersection names its own folder |
| **Smoke** | The file has open medium/low security alerts |
| **Fire and smoke** | The file has an open critical/high security alert |
| **Yellow tape** rising across the walls | Dependabot alert (on the manifest file) |
| **Red tape** falling across the walls | Code scanning alert |
| **Light beam** into the sky | A search result |
| **Cyan chevrons** on the road | Route to a file the selected file imports (**amber** if the import was inferred) |
| **Pulsing magenta dashes** on the road | Route from a file that imports the selected file |
| **Arcs** in the sky | The same import relationships, as the crow flies |
| **Green figures** | Residents. They don't mean anything; they just live there |
| **Wall with posters** | The city limits, with a few facts about the codebase pasted on |

## Getting around

**Helicopter (`1`)**: drag to orbit, Shift+drag (or right-drag) to pan, scroll to zoom.
Double-click a building to fly to it, or double-click a street to drop down and walk.

**Walk (`2`)**: click the map to capture the mouse and look around, `WASD` to move, `Shift` to run,
`Esc` to release the mouse. The crosshair names the building ahead. Press `E` (or click) to open
it in the sidebar. Walk right up to a building and its source code appears on the wall. You can't
walk through buildings or out past the city wall.

**Fly (`3`)**: like walking, but `Space` and `C` climb and descend, and moving follows where you
look.

**Touch**: left thumb is a joystick, right thumb looks around, pinch zooms (or climbs when flying).

**Minimap**: click it to jump there. It shows your heading, the city wall, security alerts and
the selected file's routes.

## Following dependencies

Select a file (click it, search for it, or pick it from the sidebar). Routes appear on the streets
to everything it imports and from everything that imports it. With a file selected, switching to
**Walk** puts you at its door facing along the first route: follow the arrows.

## Tour and links

- **Tour (`T`)**: flies over the six largest districts with captions, and stops as soon as you
  touch anything.
- **Copy link**: copies a URL with the repository, view, camera position and selected file.
  Opening it loads the repository and puts you in the same spot. Links work for GitHub
  repositories only.

## Settings

The gear opens settings: landscape palette, source text on tiles, **city residents** (they keep
the city animating, so switch them off on slow machines) and a frame-rate monitor. The sidebar
folds away with the tab on its left edge, or `[`.