# OSM City Data Loader

## 🌍 Overview

The **Geopogo OSM City Data Loader** is an Unreal Engine 5 editor plugin that fetches real-world geographic data from [OpenStreetMap](https://www.openstreetmap.org/) and procedurally generates meshes in your level — no manual modelling required.

Simply enter an address or coordinates, choose a radius, and click Load. The plugin queries the Overpass API, parses the response, and spawns categorised actors into your current level within seconds.

🏙️

- **Buildings**: Extruded wall and roof meshes with height data from OSM tags. Separate wall and roof material slots on each actor.
- **Roads**: Procedural road surfaces with miter-jointed intersections, width-scaled by road type.
- **Water**: Rivers, lakes, and water bodies filled as flat mesh polygons with a water material.
- **Parks**: Green space polygons for parks, gardens, and recreational areas.
- **Railways**: Rail line geometry for train tracks, tram lines, and metro systems.
- **Terrain**: Ground plane mesh covering the full query bounding box with water polygon cutouts.

## 📋 Requirements

| Requirement               | Detail                                                                 |
|--------------------------|------------------------------------------------------------------------|
| Unreal Engine            | 5.3 or 5.7 (Windows, 64-bit)                                          |
| Internet connection      | Required at editor time to fetch OSM data from the Overpass API       |
| Plugins enabled          | ProceduralMeshComponent — bundled with UE5, enabled automatically by OSMLoader |
| Visual Studio            | Required only if installing from source. Not needed with the pre-compiled binary release. |

**No runtime dependency.** All geometry is generated at editor time — packaged games have zero overhead from this plugin.

## 📦 Installation

1. **Download the plugin**: Download the OSMLoader zip from your Fab library after purchase.
2. **Create the Plugins folder**: In your UE5 project folder, create a folder named `Plugins` if one doesn't already exist.
3. **Copy the plugin**: Unzip and copy the `OSMLoader` folder into `YourProject/Plugins/OSMLoader/`.
4. **Open your project**: Launch UE5. When prompted to rebuild, click **Yes**. The plugin compiles automatically.
5. **Open the panel**: Go to **Window → Geopogo OSM City Data Loader** to open the dockable editor panel.

Your folder structure should look like:

```
YourProject/
  Plugins/
    OSMLoader/
      Binaries/
      Source/
      Resources/
      OSMLoader.uplugin
```

The plugin generates geometry in the **editor only**. If you package your game, OSM actors placed in the level are included as static data — no internet request happens at runtime.

## 🖼️ UI Reference

The panel is divided into several sections. Each element is labelled below.

### How to Use

#### Step 1 — Open the panel
Go to **Window → Geopogo OSM City Data Loader**. Dock it alongside your World Outliner or Details panel for a comfortable workflow.

#### Step 2 — Choose a location
You have three ways to define the area:

- **Address search** — type any place name and press Search. Coordinates fill automatically.
- **Quick Preset** — pick a city and size (S/M/L) for instant one-click loading.
- **Manual coordinates** — enter a bounding box or a centre + radius for precise control.

#### Step 3 — Select feature types
Use the **Feature Types** checkboxes to choose which geometry to generate. Uncheck categories you don't need — this speeds up loading considerably for large areas.

#### Step 4 — Assign materials (optional)
Use the **Materials** pickers to assign your project's materials before importing. Each feature type has its own slot — mix and match freely.

#### Step 5 — Configure options
- Enable **Group actors** if you want to move or clear the entire imported city as one object.
- Enable **Collision** if you need players or vehicles to interact with the geometry. Note: this makes importing slower.
- Enable **Tag for Nanite** if you plan to convert to static meshes for production-quality rendering.

#### Step 6 — Load
Click **Load from Bounding Box** or **Load from Center + Radius**. The plugin fetches data from the Overpass API and spawns all actors. A status line shows progress and a summary when done.

## ⚙️ Settings Reference

| Setting                | Description                                                                   | Default |
|-----------------------|-------------------------------------------------------------------------------|---------|
| Address Search        | Geocode a place name to coordinates via Nominatim                             | —       |
| Preset Size S/M/L    | Radius used by preset buttons — 0.5 / 1.5 / 4.0 km                           | S       |
| Bounding Box          | Explicit South / North / West / East decimal-degree bounds                    | —       |
| Center Lat / Lon     | Centre point for circular query in decimal degrees                             | 0.0 / 0.0 |
| Radius (km)          | Query radius around the centre point                                          | 0.5     |
| Terrain               | Spawn a ground plane mesh covering the bounding box                           | ✓ On   |
| Roads                 | Spawn road surface ribbon meshes                                                | ✓ On   |
| Buildings             | Spawn extruded wall + roof meshes                                              | ✓ On   |
| Water                 | Spawn water body polygon meshes                                                | ✓ On   |
| Parks                 | Spawn park / green space polygon meshes                                        | ✓ On   |
| Railways              | Spawn railway line ribbon meshes                                               | ✓ On   |
| Road Width (cm)      | Width of road meshes in Unreal centimetres                                     | 600     |
| Building Height (cm)  | Fallback extrusion height for buildings with no OSM height tag                | 1000    |
| UE Units / Metre     | Scale factor — 100 = standard UE scale (1 m = 100 cm)                        | 100     |
| Wall Material         | Material applied to building wall meshes (slot 0)                             | Built-in off-white |
| Roof Material         | Material applied to building roof meshes (slot 0)                             | Built-in dark slate |
| Road Material         | Material applied to road and intersection meshes                                | Built-in grey |
| Water Material        | Material applied to water body meshes                                           | Built-in blue |
| Park Material         | Material applied to park meshes                                                 | Built-in green |
| Railway Material      | Material applied to railway meshes                                             | Built-in steel grey |
| Tag for Nanite        | Adds OSM\_NaniteReady tag — convert via right-click for Nanite static meshes | Off     |
| Group actors          | Attach all spawned actors to a single OSM\_Group root actor                  | Off     |
| Enable collision      | Cook complex physics collision — required for pawn/vehicle interaction         | Off     |

## ❓ Frequently Asked Questions

- **The load button does nothing / times out**: The Overpass API is a free public service and can be slow or temporarily unavailable. The plugin retries up to 3 times automatically. If it still fails, wait a few minutes and try again with a smaller radius to reduce query size.
- **Buildings appear at the wrong scale**: OSM height data is in metres. The plugin converts to Unreal centimetres using the UE Units/Metre setting (default 100). If a building has no height tag, the Building Height fallback is used (default 1000 cm = 10 m ≈ 3 storeys).
- **Can I use this at runtime in a packaged game?**: The plugin is Editor-only. It cannot fetch or generate data at runtime. The actors it spawns are saved into your level and work normally in packaged builds.
- **Can I load multiple areas?**: Yes — each Load operation appends new actors without clearing previous ones. Load different areas sequentially to build a larger region. Enable Group actors before each load to keep areas organised under separate group roots.

## 📜 Attribution & License

Map data used by this plugin is sourced from **OpenStreetMap** and its contributors.

🗺️

© [OpenStreetMap contributors](https://www.openstreetmap.org/copyright). Data available under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/).

If you publish a project, game, or visualisation that uses OSM data loaded by this plugin, you are required to credit OpenStreetMap in your project credits or documentation per the ODbL terms.

The plugin code itself is © 2026 Geopogo. All Rights Reserved.