doom-osm-godmode 1.2.1 → 1.2.2

package/README.md

@@ -1,341 +1,364 @@
-## Screenshots
-
-<p align="center">
-  <img src="assets/screens/outside.jpg" alt="Map outside view" width="400"/>
-  <img src="assets/screens/inside.jpg" alt="Map inside view" width="400"/>
-</p>
-
-<p align="center"><i>Note: Some maps may show minor visual bugs or wall clipping issues. These are known and will be improved in future releases.</i></p>
-
-<p align="center">
-  <img src="assets/header.png" alt="DOOM OSM GODMODE" width="800"/>
-</p>
-
-<p align="center">
-  <a href="https://github.com/eoinjordan/doom-osm-godmode/actions"><img src="https://github.com/eoinjordan/doom-osm-godmode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://www.npmjs.com/package/doom-osm-godmode"><img src="https://img.shields.io/npm/v/doom-osm-godmode?color=brightgreen" alt="npm"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+">
-  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero deps">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="MIT"></a>
-</p>
-
----
-
-Give it a place name, a GeoJSON file, or a config — it geocodes through Nominatim, pulls polygon features from OpenStreetMap via Overpass, projects them into a connected room-and-corridor layout, and writes a PWAD in UDMF format ready for GZDoom.
-
-Zero npm dependencies. Node 20+ only.
-
-## Quick Start
-
-```bash
-# run the bundled demo (offline, no network)
-npm run demo
-
-# build a real place
-node src/cli.js build-place "Colosseum, Rome, Italy" --radius 450
-
-# search without building
-node src/cli.js search "Eiffel Tower, Paris"
-
-# build from a config file
-node src/cli.js build-config examples/colosseum.json
-```
-
-## Installation
-
-```bash
-git clone https://github.com/eoinjordan/doom-osm-godmode.git
-cd doom-osm-godmode
-npm test          # verify everything works
-npm run demo      # generate a WAD from the bundled demo site
-```
-
-Or install globally from npm:
-
-```bash
-npx doom-osm-godmode build-place "Colosseum, Rome" --radius 450
-```
-
-No `npm install` needed — there are no dependencies.
-
-## CLI Reference
-
-```
-doom-osm-godmode
-
-Commands:
-  search <query>                              Search Nominatim for a place
-  build-place <query> [options]               Geocode + OSM fetch + WAD export
-  build-config <config.json>                  Build from a JSON config file
-  demo [--out output/demo-site]               Build the bundled demo WAD
-
-Options for build-place:
-  --radius <meters>     Override bounding box with a fixed radius (default: use Nominatim bbox)
-  --map <MAPXX>         Map lump name (default: MAP01)
-  --max-rooms <count>   Cap on rooms generated (default: 12)
-  --title <name>        Override the map title
-  --out <dir>           Output directory (default: output/<slugified-title>)
-```
-
-## Programmatic API
-
-```javascript
-const { buildFromPlace, buildFromConfig, buildDemo } = require('doom-osm-godmode');
-
-// from a place name (hits Nominatim + Overpass)
-const result = await buildFromPlace('Sydney Opera House', {
-  radiusMeters: 500,
-  mapName: 'MAP01',
-  maxRooms: 10,
-  outputDir: './output/sydney'
-});
-
-// from a config file (place query or offline GeoJSON)
-const result = await buildFromConfig('examples/colosseum.json');
-
-// bundled demo (no network)
-const result = await buildDemo('./output/demo');
-```
-
-All functions return `{ outputDir, mapPath, featureCount, exportedFeatures }`.
-
-## Output
-
-Each build writes a folder containing:
-
-| File | Description |
-|------|-------------|
-| `site.json` | Normalized feature set with projected metrics |
-| `layout.json` | Room/corridor grid layout used for WAD generation |
-| `TEXTMAP.udmf` | Human-readable UDMF map geometry |
-| `MAPINFO.txt` | GZDoom map metadata (sky, music, title) |
-| `<MAPXX>.wad` | Packaged PWAD — load this in GZDoom |
-
-## Config Format
-
-Place query (network):
-
-```json
-{
-  "title": "Colosseum District",
-  "mapName": "MAP01",
-  "placeQuery": "Colosseum, Rome, Italy",
-  "radiusMeters": 450,
-  "maxRooms": 10,
-  "outputDir": "../output/colosseum"
-}
-```
-
-Offline GeoJSON:
-
-```json
-{
-  "title": "Demo Waterfront",
-  "mapName": "MAP01",
-  "inputGeoJson": "demo-site.geojson",
-  "maxRooms": 8,
-  "outputDir": "../output/demo-site"
-}
-```
-
-Relative paths in configs resolve from the config file's directory.
-
-## Architecture
-
-```
-place query / GeoJSON
-       │
-       ▼
-   geocode.js ──► Nominatim API
-       │
-       ▼
-     osm.js ────► Overpass API (polygon features)
-       │
-       ▼
- feature-set.js   project to local coords, filter, sort
-       │
-       ▼
-   layout.js      grid-based room placement + corridors + theming
-       │
-       ▼
-    udmf.js       UDMF vertices, linedefs, sidedefs, sectors, things
-       │
-       ▼
-    wad.js        binary PWAD packaging
-       │
-       ▼
-  MAP01.wad       ready for GZDoom
-```
-
-### Key Source Files
-
-| File | Purpose |
-|------|---------|
-| `src/cli.js` | CLI entry point and command router |
-| `src/workflow.js` | Build pipeline orchestrator |
-| `src/geocode.js` | Nominatim geocoding |
-| `src/osm.js` | Overpass polygon fetching |
-| `src/feature-set.js` | Feature normalization and projection |
-| `src/geo.js` | Mercator projection, bbox, polygon math |
-| `src/layout.js` | Grid room placement, corridors, theming |
-| `src/udmf.js` | UDMF text map generation |
-| `src/wad.js` | PWAD binary packing |
-| `src/lib/cli.js` | Argument parser |
-| `src/lib/fs.js` | File I/O utilities |
-
-### Room Theming
-
-Features are themed by kind:
-
-| Kind | Floor | Ceiling | Light | Notes |
-|------|-------|---------|-------|-------|
-| building | stone | flat | 152 | Default indoor |
-| water | nukage | flat | 144 | Floor at -24 |
-| park | grass | sky | 176 | Outdoor feel |
-| road | light stone | flat | 160 | Corridors |
-
-## Testing
-
-```bash
-npm test          # smoke tests via node:test
-npm run check     # syntax-check all source files
-npm run validate  # structural WAD/UDMF validation (builds + verifies integrity)
-```
-
-## Agent Playtest via doom-mcp
-
-Generated WADs can be playtested by an AI agent using [doom-mcp](https://github.com/gunnargrosch/doom-mcp) — a Rust MCP server that embeds the real DOOM engine.
-
-### Quick setup
-
-The repo includes a `.mcp.json` that configures doom-mcp to load your demo WAD:
-
-```bash
-# 1. Build a WAD first
-npm run demo
-
-# 2. Playtest it (automated agent navigation sequence)
-npm run playtest -- output/demo-site/MAP01.wad
-
-# 3. Or playtest a real-place WAD
-node src/cli.js build-place "Colosseum" --radius 450
-npm run playtest -- output/colosseum/MAP01.wad --skill 1 --ticks 300
-```
-
-### What the playtest validates
-
-The automated playtest spawns doom-mcp, loads the WAD, and runs through a navigation sequence:
-
-- **Game starts** — doom engine accepts the WAD
-- **Player spawns** — HP > 0 at spawn point
-- **Player can move** — position changes across multiple actions
-- **Player survives** — doesn't die during baby-difficulty walkthrough
-
-### Using doom-mcp interactively
-
-For interactive agent playtesting (e.g., in Claude Code or Cursor):
-
-```json
-{
-  "mcpServers": {
-    "doom": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "doom-mcp"],
-      "env": {
-        "DOOM_WAD_PATH": "/path/to/your/MAP01.wad"
-      }
-    }
-  }
-}
-```
-
-Then tell the agent: *"Play this DOOM level and tell me if it's fun"*
-
-### CI integration
-
-The `playtest.yml` workflow runs structural validation on every tag push and can be triggered manually for any place:
-
-```
-Actions → Playtest → Run workflow → Enter place name → Go
-```
-
-## Playing the WAD
-
-```bash
-# GZDoom (adjust path to your install)
-gzdoom -file output/colosseum/MAP01.wad
-```
-
-The WAD is a PWAD — it layers on top of any IWAD (DOOM2.WAD, FREEDOOM2.WAD, etc.).
-
-## Hand-Crafted Buildings
-
-The OSM pipeline creates grid-based rooms. For architecturally accurate buildings (cathedrals, temples, etc.), use a hand-crafted script:
-
-```bash
-# Build the Galway Cathedral demo (cross-shaped plan, dome, catacombs)
-node scripts/build-galway-cathedral.js
-
-# Launch in GZDoom
-gzdoom -iwad DOOM2.WAD -file output/galway-cathedral-v3/MAP01.wad +map MAP01
-```
-
-The cathedral builder demonstrates the `UDMFBuilder` class with polygon-based sector creation, self-validation, and teleporter-linked sub-areas. Use it as a template for new hand-crafted maps.
-
-### Validate any WAD
-
-```bash
-# Structural UDMF diagnostic (checks for duplicate linedefs, etc.)
-node scripts/diagnose-udmf.js output/galway-cathedral-v3/TEXTMAP.udmf
-
-# Agent playtest via doom-mcp
-npm run playtest -- output/galway-cathedral-v3/MAP01.wad
-```
-
-## UDMF Geometry Rules
-
-Common issues found when generating DOOM maps from real-world data:
-
-| Issue | Symptom | Fix |
-|-------|---------|-----|
-| Duplicate linedefs (same vertex pair) | Flickering/transparent walls | Use a single polygon for complex shapes; deduplicate in `addInnerSector` |
-| Collinear overlapping linedefs | See-through walls, BSP errors | Never let two linedefs share the same 2D line segment |
-| Inner sector outside parent bounds | Rendering void, hall-of-mirrors | Ensure all inner sector vertices are strictly inside the outer polygon |
-| Separate rooms at same crossing | Duplicate shared edges | Use ONE polygon for the union shape (e.g., a cross), not overlapping rectangles |
-| Underground areas sharing x,y with upper | DOOM 2.5D sector conflict | Place underground areas at different x,y coords; connect via teleporter |
-| Invisible walls on two-sided linedefs | Side walls transparent where floor heights match | Set `wrapmidtex = true` + `blocking = true` + `texturemiddle` on the two-sided linedef |
-| Floating mid-textures on promoted linedefs | Choppy half-height walls | Clear `texturemiddle` when promoting one-sided to two-sided; use upper/lower instead |
-| Zero-height pillar sectors (floor = ceiling) | Player stuck, node builder errors | Use Thing-based pillars (type 30) instead of sector-based pillars |
-
-### Repeatable pattern for future OSM meshes
-
-1. Run `node src/cli.js build-place ...` for the grid-room WAD
-2. Run `node scripts/diagnose-udmf.js output/<name>/TEXTMAP.udmf` to check geometry
-3. Run `npm run playtest -- output/<name>/MAP01.wad` for engine validation
-4. If the grid rooms are too abstract, create a hand-crafted script (see `scripts/build-galway-cathedral.js`)
-5. Always run self-validation before writing the WAD
-
-## Notes
-
-- Network commands use public OSM infrastructure (Nominatim, Overpass). Keep requests reasonable.
-- Only polygon features become rooms. Roads and linear features are not yet carved into sectors.
-- The layout is a blockout interpretation — connected rooms reflecting real feature hierarchy, not pixel-perfect street geometry.
-
-## Roadmap
-
-- exact polygon-to-sector carving (replace grid rooms with real building outlines)
-- road and canal line buffering into traversable sectors
-- Doom encounter placement (monsters, ammo, weapons)
-- texture themes per location style
-- multi-map episode generation
-- freeform agent-described layouts (no OSM needed)
-- automatic duplicate linedef detection in the OSM pipeline
-
-## Contributing
-
-PRs welcome. Run `npm test` and `npm run check` before submitting.
-
-## License
-
-MIT — see [LICENSE](LICENSE)
+<p align="center">
+  <a href="https://github.com/eoinjordan/doom-osm-godmode/releases"><img src="https://img.shields.io/github/v/tag/eoinjordan/doom-osm-godmode?sort=semver&label=release&color=brightgreen" alt="release tag"></a>
+  <a href="https://www.npmjs.com/package/doom-osm-godmode"><img src="https://img.shields.io/npm/v/doom-osm-godmode?color=brightgreen" alt="npm"></a>
+  <a href="https://github.com/eoinjordan/doom-osm-godmode/actions"><img src="https://github.com/eoinjordan/doom-osm-godmode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+">
+  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero deps">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="MIT"></a>
+</p>
+
+<p align="center">
+  <img src="assets/header.png" alt="DOOM OSM GODMODE" width="800"/>
+</p>
+
+---
+
+Give it a place name, a GeoJSON file, or a config — it geocodes through Nominatim, pulls polygon features from OpenStreetMap via Overpass, projects them into a connected room-and-corridor layout, and writes a PWAD in UDMF format ready for GZDoom.
+
+Zero npm dependencies. Node 20+ only.
+
+## Quick Start
+
+```bash
+# run the bundled demo (offline, no network)
+npm run demo
+
+# build a real place
+node src/cli.js build-place "Colosseum, Rome, Italy" --radius 450
+node src/cli.js build-place "Eiffel Tower, Paris" --radius 450
+
+# hand-crafted architecturally accurate building
+node scripts/build-galway-cathedral.js
+
+# search without building
+node src/cli.js search "Eiffel Tower, Paris"
+
+# build from a config file
+node src/cli.js build-config examples/colosseum.json
+```
+
+## Installation
+
+```bash
+git clone https://github.com/eoinjordan/doom-osm-godmode.git
+cd doom-osm-godmode
+npm test          # verify everything works
+npm run demo      # generate a WAD from the bundled demo site
+```
+
+Or install globally from npm:
+
+```bash
+npx doom-osm-godmode build-place "Colosseum, Rome" --radius 450
+```
+
+No `npm install` needed — there are no dependencies.
+
+
+Start the map on GZDOOM or Ultimate on Windows:
+
+```
+"C:\Games\GZDoom\gzdoom.exe" -iwad "C:\Program Files (x86)\Steam\steamapps\common\Ultimate Doom\base\doom2\DOOM2.WAD" -file "C:\Users\Eoin\git\doom-osm-wad\output\galway-cathedral-v3\MAP01.wad" +map MAP01
+```
+
+<img width="899" height="689" alt="image" src="https://github.com/user-attachments/assets/894904fe-5e10-4226-ad60-72ff50e7b9ce" />
+
+## Screenshots
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/eoinjordan/doom-osm-godmode/main/assets/screens/outside.jpg" alt="Galway Cathedral outside" width="400"/>
+  <img src="https://raw.githubusercontent.com/eoinjordan/doom-osm-godmode/main/assets/screens/inside.jpg" alt="Galway Cathedral inside" width="400"/>
+</p>
+
+<p align="center"><em>Galway Cathedral — hand-crafted map. Some visual clipping bugs are known and will be addressed in future releases.</em></p>
+
+## CLI Reference
+
+```
+doom-osm-godmode
+
+Commands:
+  search <query>                              Search Nominatim for a place
+  build-place <query> [options]               Geocode + OSM fetch + WAD export
+  build-config <config.json>                  Build from a JSON config file
+  demo [--out output/demo-site]               Build the bundled demo WAD
+
+Options for build-place:
+  --radius <meters>     Override bounding box with a fixed radius (default: use Nominatim bbox)
+  --map <MAPXX>         Map lump name (default: MAP01)
+  --max-rooms <count>   Cap on rooms generated (default: 12)
+  --title <name>        Override the map title
+  --out <dir>           Output directory (default: output/<slugified-title>)
+```
+
+## Programmatic API
+
+```javascript
+const { buildFromPlace, buildFromConfig, buildDemo } = require('doom-osm-godmode');
+
+// from a place name (hits Nominatim + Overpass)
+const result = await buildFromPlace('Sydney Opera House', {
+  radiusMeters: 500,
+  mapName: 'MAP01',
+  maxRooms: 10,
+  outputDir: './output/sydney'
+});
+
+// from a config file (place query or offline GeoJSON)
+const result = await buildFromConfig('examples/colosseum.json');
+
+// bundled demo (no network)
+const result = await buildDemo('./output/demo');
+```
+
+All functions return `{ outputDir, mapPath, featureCount, exportedFeatures }`.
+
+## Output
+
+Each build writes a folder containing:
+
+| File | Description |
+|------|-------------|
+| `site.json` | Normalized feature set with projected metrics |
+| `layout.json` | Room/corridor grid layout used for WAD generation |
+| `TEXTMAP.udmf` | Human-readable UDMF map geometry |
+| `MAPINFO.txt` | GZDoom map metadata (sky, music, title) |
+| `<MAPXX>.wad` | Packaged PWAD — load this in GZDoom |
+
+## Config Format
+
+Place query (network):
+
+```json
+{
+  "title": "Colosseum District",
+  "mapName": "MAP01",
+  "placeQuery": "Colosseum, Rome, Italy",
+  "radiusMeters": 450,
+  "maxRooms": 10,
+  "outputDir": "../output/colosseum"
+}
+```
+
+Offline GeoJSON:
+
+```json
+{
+  "title": "Demo Waterfront",
+  "mapName": "MAP01",
+  "inputGeoJson": "demo-site.geojson",
+  "maxRooms": 8,
+  "outputDir": "../output/demo-site"
+}
+```
+
+Relative paths in configs resolve from the config file's directory.
+
+## Architecture
+
+```
+place query / GeoJSON
+       │
+       ▼
+   geocode.js ──► Nominatim API
+       │
+       ▼
+     osm.js ────► Overpass API (polygon features)
+       │
+       ▼
+ feature-set.js   project to local coords, filter, sort
+       │
+       ▼
+   layout.js      grid-based room placement + corridors + theming
+       │
+       ▼
+    udmf.js       UDMF vertices, linedefs, sidedefs, sectors, things
+       │
+       ▼
+    wad.js        binary PWAD packaging
+       │
+       ▼
+  MAP01.wad       ready for GZDoom
+```
+
+### Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/cli.js` | CLI entry point and command router |
+| `src/workflow.js` | Build pipeline orchestrator |
+| `src/geocode.js` | Nominatim geocoding |
+| `src/osm.js` | Overpass polygon fetching |
+| `src/feature-set.js` | Feature normalization and projection |
+| `src/geo.js` | Mercator projection, bbox, polygon math |
+| `src/layout.js` | Grid room placement, corridors, theming |
+| `src/udmf.js` | UDMF text map generation |
+| `src/wad.js` | PWAD binary packing |
+| `src/lib/cli.js` | Argument parser |
+| `src/lib/fs.js` | File I/O utilities |
+
+### Room Theming
+
+Features are themed by kind:
+
+| Kind | Floor | Ceiling | Light | Notes |
+|------|-------|---------|-------|-------|
+| building | stone | flat | 152 | Default indoor |
+| water | nukage | flat | 144 | Floor at -24 |
+| park | grass | sky | 176 | Outdoor feel |
+| road | light stone | flat | 160 | Corridors |
+
+## Testing
+
+```bash
+npm test          # smoke tests via node:test
+npm run check     # syntax-check all source files
+npm run validate  # structural WAD/UDMF validation (builds + verifies integrity)
+```
+
+## Agent Playtest via doom-mcp
+
+Generated WADs can be playtested by an AI agent using [doom-mcp](https://github.com/gunnargrosch/doom-mcp) — a Rust MCP server that embeds the real DOOM engine.
+
+### Quick setup
+
+The repo includes a `.mcp.json` that configures doom-mcp to load your demo WAD:
+
+```bash
+# 1. Build a WAD first
+npm run demo
+
+# 2. Playtest it (automated agent navigation sequence)
+npm run playtest -- output/demo-site/MAP01.wad
+
+# 3. Or playtest a real-place WAD
+node src/cli.js build-place "Colosseum" --radius 450
+npm run playtest -- output/colosseum/MAP01.wad --skill 1 --ticks 300
+```
+
+### What the playtest validates
+
+The automated playtest spawns doom-mcp, loads the WAD, and runs through a navigation sequence:
+
+- **Game starts** — doom engine accepts the WAD
+- **Player spawns** — HP > 0 at spawn point
+- **Player can move** — position changes across multiple actions
+- **Player survives** — doesn't die during baby-difficulty walkthrough
+
+### Using doom-mcp interactively
+
+For interactive agent playtesting (e.g., in Claude Code or Cursor):
+
+```json
+{
+  "mcpServers": {
+    "doom": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "doom-mcp"],
+      "env": {
+        "DOOM_WAD_PATH": "/path/to/your/MAP01.wad"
+      }
+    }
+  }
+}
+```
+
+Then tell the agent: *"Play this DOOM level and tell me if it's fun"*
+
+### CI integration
+
+The `playtest.yml` workflow runs structural validation on every tag push and can be triggered manually for any place:
+
+```
+Actions → Playtest → Run workflow → Enter place name → Go
+```
+
+## Playing the WAD
+
+```bash
+# GZDoom (adjust path to your install)
+gzdoom -file output/colosseum/MAP01.wad
+```
+
+The WAD is a PWAD — it layers on top of any IWAD (DOOM2.WAD, FREEDOOM2.WAD, etc.).
+
+## Hand-Crafted Buildings
+
+The OSM pipeline creates grid-based rooms. For architecturally accurate buildings (cathedrals, temples, etc.), use a hand-crafted script:
+
+```bash
+# Build the Galway Cathedral demo (cross-shaped plan, green copper dome, grand nave)
+node scripts/build-galway-cathedral.js
+
+# Launch in GZDoom
+gzdoom -iwad DOOM2.WAD -file output/galway-cathedral-v3/MAP01.wad +map MAP01
+```
+
+The cathedral builder demonstrates the `UDMFBuilder` class with polygon-based sector creation, grand interior aisle, raised chancel, self-validation, and exterior forecourt. Use it as a template for new hand-crafted maps.
+
+**Example maps included:**
+
+| Map | Type | Script / Command |
+|-----|------|------------------|
+| Galway Cathedral | Hand-crafted | `node scripts/build-galway-cathedral.js` |
+| Colosseum, Rome | OSM / live | `node src/cli.js build-place "Colosseum, Rome, Italy" --radius 450` |
+| Eiffel Tower, Paris | OSM / live | `node src/cli.js build-place "Eiffel Tower, Paris" --radius 450` |
+| Demo Waterfront | Offline GeoJSON | `npm run demo` |
+
+### Validate any WAD
+
+```bash
+# Structural UDMF diagnostic (checks for duplicate linedefs, etc.)
+node scripts/diagnose-udmf.js output/galway-cathedral-v3/TEXTMAP.udmf
+
+# Agent playtest via doom-mcp
+npm run playtest -- output/galway-cathedral-v3/MAP01.wad
+```
+
+## UDMF Geometry Rules
+
+Common issues found when generating DOOM maps from real-world data:
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Duplicate linedefs (same vertex pair) | Flickering/transparent walls | Use a single polygon for complex shapes; deduplicate in `addInnerSector` |
+| Collinear overlapping linedefs | See-through walls, BSP errors | Never let two linedefs share the same 2D line segment |
+| Inner sector outside parent bounds | Rendering void, hall-of-mirrors | Ensure all inner sector vertices are strictly inside the outer polygon |
+| Separate rooms at same crossing | Duplicate shared edges | Use ONE polygon for the union shape (e.g., a cross), not overlapping rectangles |
+| Underground areas sharing x,y with upper | DOOM 2.5D sector conflict | Place underground areas at different x,y coords; connect via teleporter |
+| Invisible walls on two-sided linedefs | Side walls transparent where floor heights match | Set `wrapmidtex = true` + `blocking = true` + `texturemiddle` on the two-sided linedef |
+| Floating mid-textures on promoted linedefs | Choppy half-height walls | Clear `texturemiddle` when promoting one-sided to two-sided; use upper/lower instead |
+| Zero-height pillar sectors (floor = ceiling) | Player stuck, node builder errors | Use Thing-based pillars (type 30) instead of sector-based pillars |
+
+### Repeatable pattern for future OSM meshes
+
+1. Run `node src/cli.js build-place ...` for the grid-room WAD
+2. Run `node scripts/diagnose-udmf.js output/<name>/TEXTMAP.udmf` to check geometry
+3. Run `npm run playtest -- output/<name>/MAP01.wad` for engine validation
+4. If the grid rooms are too abstract, create a hand-crafted script (see `scripts/build-galway-cathedral.js`)
+5. Always run self-validation before writing the WAD
+
+## Notes
+
+- Network commands use public OSM infrastructure (Nominatim, Overpass). Keep requests reasonable.
+- Only polygon features become rooms. Roads and linear features are not yet carved into sectors.
+- The layout is a blockout interpretation — connected rooms reflecting real feature hierarchy, not pixel-perfect street geometry.
+
+## Roadmap
+
+- exact polygon-to-sector carving (replace grid rooms with real building outlines)
+- road and canal line buffering into traversable sectors
+- Doom encounter placement (monsters, ammo, weapons)
+- texture themes per location style
+- multi-map episode generation
+- freeform agent-described layouts (no OSM needed)
+- automatic duplicate linedef detection in the OSM pipeline
+
+## Contributing
+
+PRs welcome. Run `npm test` and `npm run check` before submitting.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doom-osm-godmode",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "DOOM OSM GODMODE — Turn any real-world place into a playable GZDoom WAD. Geocode → OSM → UDMF → PWAD. Zero dependencies.",
   "type": "commonjs",
   "main": "src/workflow.js",

package/scripts/build-galway-cathedral.js

@@ -317,53 +317,51 @@ function buildCathedral() {
   const b = new UDMFBuilder();
 
   // ── Dimensions (map units) ──
-  const NAVE_HW = 192;         // nave half-width
-  const NAVE_LEN = 1024;       // nave length south of crossing
-  const CHANCEL_LEN = 640;     // chancel length north of crossing
-  const TRANS_HW = 192;        // transept half-width (same as nave)
-  const TRANS_LEN = 512;       // transept arm length each side
-  const DOME_R = 256;          // dome radius
+  const NAVE_HW = 256;         // nave half-width
+  const NAVE_LEN = 1408;       // nave length south of crossing
+  const CHANCEL_LEN = 896;     // chancel length north of crossing
+  const TRANS_HW = 256;        // transept half-width (same as nave)
+  const TRANS_LEN = 704;       // transept arm length each side
+  const DOME_R = 320;          // dome radius
   const SPIRE_R = 48;          // spire radius
-  const TOWER_SIZE = 192;      // entrance tower footprint
+  const TOWER_SIZE = 256;      // entrance tower footprint
 
   // Heights
   const FLOOR = 0;
-  const NAVE_CEIL = 256;
-  const DOME_CEIL = 384;
-  const SPIRE_CEIL = 512;
-  const TOWER_CEIL = 320;
+  const NAVE_CEIL = 384;
+  const DOME_CEIL = 544;
+  const SPIRE_CEIL = 672;
+  const TOWER_CEIL = 448;
   // Sky ceiling should match the tallest directly-adjacent non-sky sector.
   // F_SKY1 renders as sky regardless of height, so the numeric value
   // only affects upper-texture gap sizing. Matching eliminates artifacts.
-  const CARPARK_CEIL = 320;
-  const CATA_FLOOR = -192;
-  const CATA_CEIL = -16;
+  const CARPARK_CEIL = 448;
+  const CARPARK_FLOOR = -16;
 
   // Textures
   const STONE = 'STONE2';
-  const BIGSTONE = 'BIGBRIK1';
+  const BIGSTONE = 'STONE3';
   const MARBLE_F = 'FLAT1';
   const CEIL_INT = 'CEIL1_1';
   const SKY = 'F_SKY1';
   const FLAT_GREY = 'FLAT5_4';
   const DOME_TEX = 'CEIL5_2';
   const METAL = 'METAL';
-  const COPPER_W = 'BROWNGRN';
+  const COPPER_W = 'GRAY7';
   const TILE_F = 'FLOOR0_1';
-  const CATA_WALL = 'STONE3';
-  const CATA_FLOOR_T = 'FLOOR7_1';
+  const AISLE_F = 'FLOOR4_8';
 
   // ════════════════════════════════════════════════════════════
   // 1. CARPARK (outer boundary, sky ceiling)
   // ════════════════════════════════════════════════════════════
-  const CP = 3200;
+  const CP = 4608;
   const carparkSector = b.addPolySector([
     [-CP / 2, -CP / 2],
     [CP / 2, -CP / 2],
     [CP / 2, CP / 2],
     [-CP / 2, CP / 2]
   ], {
-    floorH: FLOOR, ceilH: CARPARK_CEIL,
+    floorH: CARPARK_FLOOR, ceilH: CARPARK_CEIL,
     floorTex: FLAT_GREY, ceilTex: SKY, light: 192
   }, STONE);
 
@@ -407,6 +405,38 @@ function buildCathedral() {
   }, carparkSector, BIGSTONE);
   const crossLdEnd = b.linedefs.length;
 
+  // Center aisle to give the nave a more ceremonial, grand feel.
+  b.addInnerSector([
+    [-72, -NAVE_LEN + 48],
+    [72, -NAVE_LEN + 48],
+    [72, CHANCEL_LEN - 80],
+    [-72, CHANCEL_LEN - 80]
+  ], {
+    floorH: FLOOR + 4, ceilH: NAVE_CEIL,
+    floorTex: AISLE_F, ceilTex: CEIL_INT, light: 188
+  }, crossSector, BIGSTONE);
+
+  // Side aisles for depth and visual layering inside the nave.
+  b.addInnerSector([
+    [-NAVE_HW + 24, -NAVE_LEN + 96],
+    [-NAVE_HW + 116, -NAVE_LEN + 96],
+    [-NAVE_HW + 116, CHANCEL_LEN - 128],
+    [-NAVE_HW + 24, CHANCEL_LEN - 128]
+  ], {
+    floorH: FLOOR + 2, ceilH: NAVE_CEIL,
+    floorTex: TILE_F, ceilTex: CEIL_INT, light: 174
+  }, crossSector, BIGSTONE);
+
+  b.addInnerSector([
+    [NAVE_HW - 116, -NAVE_LEN + 96],
+    [NAVE_HW - 24, -NAVE_LEN + 96],
+    [NAVE_HW - 24, CHANCEL_LEN - 128],
+    [NAVE_HW - 116, CHANCEL_LEN - 128]
+  ], {
+    floorH: FLOOR + 2, ceilH: NAVE_CEIL,
+    floorTex: TILE_F, ceilTex: CEIL_INT, light: 174
+  }, crossSector, BIGSTONE);
+
   // Make cross walls SOLID with wrapmidtex.
   // In DOOM, two-sided linedefs between same-floor sectors are transparent.
   // wrapmidtex tiles the mid-texture to fill the full height = opaque wall.
@@ -541,87 +571,27 @@ function buildCathedral() {
   }
 
   // ════════════════════════════════════════════════════════════
-  // 9. TELEPORTER PAD — in east transept, sends to catacombs
-  // ════════════════════════════════════════════════════════════
-  const TELE_TID_DOWN = 1;
-  const TELE_TID_UP = 2;
-
-  const telePadSector = b.addInnerSector([
-    [NAVE_HW + TRANS_LEN - 128, -64],
-    [NAVE_HW + TRANS_LEN - 32, -64],
-    [NAVE_HW + TRANS_LEN - 32, 64],
-    [NAVE_HW + TRANS_LEN - 128, 64]
-  ], {
-    floorH: FLOOR + 8, ceilH: NAVE_CEIL,
-    floorTex: 'GATE4', ceilTex: CEIL_INT, light: 255
-  }, crossSector, METAL);
-
-  // Teleport linedef across the middle of the pad (walk-over)
-  b.addSpecialLinedef(
-    [NAVE_HW + TRANS_LEN - 80, -64],
-    [NAVE_HW + TRANS_LEN - 80, 64],
-    telePadSector, telePadSector,
-    70,   // Teleport
-    [TELE_TID_DOWN, 0, 1],
-    '-'
-  );
-
-  // ════════════════════════════════════════════════════════════
-  // 10. CATACOMBS — separate area east of cathedral (x=1200+)
+  // 9. EXTERIOR PLAZA — front forecourt with broad approach
   // ════════════════════════════════════════════════════════════
-  const CATA_X = 1200;
-  const CATA_Y = 0;
-  const CATA_W = 768;
-  const CATA_H = 512;
-
-  const cataSector = b.addPolySector([
-    [CATA_X - CATA_W / 2, CATA_Y - CATA_H / 2],
-    [CATA_X + CATA_W / 2, CATA_Y - CATA_H / 2],
-    [CATA_X + CATA_W / 2, CATA_Y + CATA_H / 2],
-    [CATA_X - CATA_W / 2, CATA_Y + CATA_H / 2]
+  b.addInnerSector([
+    [-512, -NAVE_LEN - 320],
+    [512, -NAVE_LEN - 320],
+    [512, -NAVE_LEN - 64],
+    [-512, -NAVE_LEN - 64]
   ], {
-    floorH: CATA_FLOOR, ceilH: CATA_CEIL,
-    floorTex: CATA_FLOOR_T, ceilTex: 'CEIL3_3', light: 96
-  }, CATA_WALL);
-
-  // Catacomb side chambers (4 alcoves)
-  const chW = 192, chH = 128;
-  for (let i = -1; i <= 1; i += 2) {
-    for (let j = -1; j <= 1; j += 2) {
-      const cx = CATA_X + i * 200;
-      const cy = CATA_Y + j * 128;
-      b.addInnerSector([
-        [cx - chW / 2, cy - chH / 2],
-        [cx + chW / 2, cy - chH / 2],
-        [cx + chW / 2, cy + chH / 2],
-        [cx - chW / 2, cy + chH / 2]
-      ], {
-        floorH: CATA_FLOOR, ceilH: CATA_CEIL,
-        floorTex: CATA_FLOOR_T, ceilTex: 'CEIL3_3', light: 80
-      }, cataSector, CATA_WALL);
-    }
-  }
+    floorH: CARPARK_FLOOR + 8, ceilH: CARPARK_CEIL,
+    floorTex: 'FLOOR5_1', ceilTex: SKY, light: 200
+  }, carparkSector, STONE);
 
-  // Return teleporter pad in catacombs
-  const cataReturnSector = b.addInnerSector([
-    [CATA_X - 48, CATA_Y + CATA_H / 2 - 96],
-    [CATA_X + 48, CATA_Y + CATA_H / 2 - 96],
-    [CATA_X + 48, CATA_Y + CATA_H / 2 - 32],
-    [CATA_X - 48, CATA_Y + CATA_H / 2 - 32]
+  b.addInnerSector([
+    [-300, -NAVE_LEN - 64],
+    [300, -NAVE_LEN - 64],
+    [300, -NAVE_LEN],
+    [-300, -NAVE_LEN]
   ], {
-    floorH: CATA_FLOOR + 8, ceilH: CATA_CEIL,
-    floorTex: 'GATE4', ceilTex: 'CEIL3_3', light: 255
-  }, cataSector, METAL);
-
-  // Return teleport linedef
-  b.addSpecialLinedef(
-    [CATA_X, CATA_Y + CATA_H / 2 - 96],
-    [CATA_X, CATA_Y + CATA_H / 2 - 32],
-    cataReturnSector, cataReturnSector,
-    70,
-    [TELE_TID_UP, 0, 1],
-    '-'
-  );
+    floorH: FLOOR - 4, ceilH: CARPARK_CEIL,
+    floorTex: 'MFLR8_2', ceilTex: SKY, light: 208
+  }, carparkSector, STONE);
 
   // ════════════════════════════════════════════════════════════
   // THINGS
@@ -630,17 +600,20 @@ function buildCathedral() {
   // Player start — in nave, facing north toward altar
   b.addThing(0, -NAVE_LEN + 256, 1, 90);
 
-  // Teleport destinations
-  b.addThing(CATA_X, CATA_Y, 14, 90, { tid: TELE_TID_DOWN });
-  b.addThing(NAVE_HW + TRANS_LEN - 160, 0, 14, 270, { tid: TELE_TID_UP });
-
   // Candelabras in nave
-  for (let i = 0; i < 5; i++) {
-    const ty = -NAVE_LEN + 200 + i * 160;
+  for (let i = 0; i < 9; i++) {
+    const ty = -NAVE_LEN + 220 + i * 190;
     b.addThing(-NAVE_HW + 64, ty, 35, 0);
     b.addThing(NAVE_HW - 64, ty, 35, 0);
   }
 
+  // Mid-aisle lights for the grand interior rhythm.
+  for (let i = 0; i < 7; i++) {
+    const ty = -NAVE_LEN + 300 + i * 220;
+    b.addThing(-40, ty, 44, 0);
+    b.addThing(40, ty, 44, 0);
+  }
+
   // Torches in transepts
   b.addThing(-NAVE_HW - TRANS_LEN + 64, 0, 46, 0);
   b.addThing(NAVE_HW + TRANS_LEN - 160, 0, 46, 0);
@@ -657,19 +630,26 @@ function buildCathedral() {
   b.addThing(-NAVE_HW - 32, -NAVE_LEN - 32, 46, 0);
   b.addThing(NAVE_HW + 32, -NAVE_LEN - 32, 46, 0);
 
-  // Catacomb torches
-  for (let i = -1; i <= 1; i += 2) {
-    for (let j = -1; j <= 1; j += 2) {
-      b.addThing(CATA_X + i * 200, CATA_Y + j * 128, 44, 0);
-    }
+  // Plaza lights and markers for exterior style.
+  for (let x = -420; x <= 420; x += 140) {
+    b.addThing(x, -NAVE_LEN - 220, 46, 0);
   }
 
-  // Monsters in catacombs
-  b.addThing(CATA_X - 200, CATA_Y - 128, 3001, 0);
-  b.addThing(CATA_X + 200, CATA_Y + 128, 3001, 0);
-  b.addThing(CATA_X - 200, CATA_Y + 128, 3002, 0);
-  b.addThing(CATA_X + 200, CATA_Y - 128, 3002, 0);
-  b.addThing(CATA_X, CATA_Y, 3003, 0);
+  for (let x = -560; x <= 560; x += 280) {
+    b.addThing(x, -NAVE_LEN - 460, 35, 0);
+  }
+
+  // Interior encounters and cast.
+  b.addThing(-120, -360, 3001, 0);
+  b.addThing(120, -280, 3001, 0);
+  b.addThing(-180, 140, 3002, 0);
+  b.addThing(180, 180, 3002, 0);
+  b.addThing(0, CHANCEL_LEN - 210, 3003, 180);
+
+  // Exterior encounters around the forecourt.
+  b.addThing(-340, -NAVE_LEN - 280, 3001, 90);
+  b.addThing(340, -NAVE_LEN - 280, 3001, 270);
+  b.addThing(0, -NAVE_LEN - 500, 3002, 90);
 
   // Weapons and items
   b.addThing(0, -NAVE_LEN + 64, 2001, 0);        // shotgun at entrance
@@ -714,9 +694,9 @@ function main() {
     title: 'Galway Cathedral',
     version: 3,
     mapName: 'MAP01',
-    description: 'Cross-shaped limestone cathedral with green copper dome, twin towers, teleporter catacombs, and carpark',
-    features: ['cross polygon', 'dome', 'spire', 'twin towers', 'teleporter catacombs',
-               'nave pillars', 'raised chancel', 'altar', 'carpark']
+    description: 'Grand cross-shaped limestone cathedral with expanded nave, twin towers, ceremonial aisle, and exterior forecourt',
+    features: ['cross polygon', 'dome', 'spire', 'twin towers',
+           'grand aisle', 'side aisles', 'nave pillars', 'raised chancel', 'altar', 'forecourt']
   }, null, 2);
 
   const wadBuffer = createWadBuffer({
@@ -747,7 +727,8 @@ function main() {
   console.log('    + Nave pillars');
   console.log('    + Raised chancel + altar');
   console.log('    + Flat grey carpark exterior');
-  console.log('    + Catacombs (teleporter from east transept)');
+  console.log('    + Grand nave aisle + side aisles');
+  console.log('    + Exterior forecourt with approach lights');
   console.log('    + Self-validation pass');
 
   console.log('\n  Launch:');