doom-osm-godmode 1.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,332 @@
+<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=cc2200" 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)

package/examples/colosseum.json

@@ -0,0 +1,8 @@
+{
+  "title": "Colosseum District",
+  "mapName": "MAP01",
+  "placeQuery": "Colosseum, Rome, Italy",
+  "radiusMeters": 450,
+  "maxRooms": 10,
+  "outputDir": "../output/colosseum"
+}

package/examples/demo-site.geojson

@@ -0,0 +1,101 @@
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Harbor Hall",
+        "kind": "building"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [12.49205, 41.88985],
+            [12.49228, 41.88985],
+            [12.49228, 41.89004],
+            [12.49205, 41.89004],
+            [12.49205, 41.88985]
+          ]
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "North Arcade",
+        "kind": "building"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [12.49234, 41.89012],
+            [12.49262, 41.89012],
+            [12.49262, 41.89031],
+            [12.49234, 41.89031],
+            [12.49234, 41.89012]
+          ]
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Garden Court",
+        "kind": "park"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [12.49200, 41.89019],
+            [12.49222, 41.89019],
+            [12.49222, 41.89039],
+            [12.49200, 41.89039],
+            [12.49200, 41.89019]
+          ]
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "Reflecting Basin",
+        "kind": "water"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [12.49240, 41.88978],
+            [12.49271, 41.88978],
+            [12.49271, 41.88996],
+            [12.49240, 41.88996],
+            [12.49240, 41.88978]
+          ]
+        ]
+      }
+    },
+    {
+      "type": "Feature",
+      "properties": {
+        "name": "South Gate",
+        "kind": "building"
+      },
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [12.49278, 41.88996],
+            [12.49299, 41.88996],
+            [12.49299, 41.89015],
+            [12.49278, 41.89015],
+            [12.49278, 41.88996]
+          ]
+        ]
+      }
+    }
+  ]
+}
+

package/examples/demo-site.json

@@ -0,0 +1,7 @@
+{
+  "title": "Demo Waterfront",
+  "mapName": "MAP01",
+  "inputGeoJson": "demo-site.geojson",
+  "maxRooms": 8,
+  "outputDir": "../output/demo-site"
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "doom-osm-godmode",
+  "version": "1.2.0",
+  "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",
+  "bin": {
+    "doom-osm-godmode": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node --check src/cli.js && node --check src/feature-set.js && node --check src/geocode.js && node --check src/geo.js && node --check src/layout.js && node --check src/osm.js && node --check src/udmf.js && node --check src/wad.js && node --check src/workflow.js && node --check src/lib/cli.js && node --check src/lib/fs.js",
+    "test": "node --test test/*.test.js",
+    "demo": "node src/cli.js demo",
+    "search": "node src/cli.js search",
+    "build:config": "node src/cli.js build-config",
+    "build:place": "node src/cli.js build-place",
+    "validate": "node --test test/validate-wad.test.js",
+    "playtest": "node scripts/playtest-wad.mjs",
+    "version": "node -e \"console.log(require('./package.json').version)\"",
+    "prepack": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "doom",
+    "godmode",
+    "iddqd",
+    "wad",
+    "gzdoom",
+    "udmf",
+    "openstreetmap",
+    "osm",
+    "level-generation",
+    "procedural-generation",
+    "map-generator",
+    "mcp"
+  ],
+  "author": "Eoin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eoinjordan/doom-osm-godmode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eoinjordan/doom-osm-godmode/issues"
+  },
+  "homepage": "https://github.com/eoinjordan/doom-osm-godmode#readme"
+}
+

package/src/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+const path = require('node:path');
+const { parseArgs, printHelp, readNumberFlag, readStringFlag } = require('./lib/cli.js');
+const { searchPlace } = require('./geocode.js');
+const { buildDemo, buildFromConfig, buildFromPlace } = require('./workflow.js');
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = args._;
+
+  if (!command || command === 'help' || command === '--help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'search') {
+    const query = rest.join(' ').trim();
+    if (!query) {
+      throw new Error('search requires a place query.');
+    }
+
+    const results = await searchPlace(query, 5);
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
+  if (command === 'build-config') {
+    const configPath = rest[0];
+    if (!configPath) {
+      throw new Error('build-config requires a config file path.');
+    }
+
+    const result = await buildFromConfig(configPath);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (command === 'build-place') {
+    const query = rest.join(' ').trim();
+    if (!query) {
+      throw new Error('build-place requires a place query.');
+    }
+
+    const result = await buildFromPlace(query, {
+      radiusMeters: readNumberFlag(args, 'radius', undefined),
+      mapName: readStringFlag(args, 'map', 'MAP01'),
+      maxRooms: readNumberFlag(args, 'max-rooms', 12),
+      title: readStringFlag(args, 'title', undefined),
+      outputDir: args.out ? path.resolve(args.out) : undefined
+    });
+
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (command === 'demo') {
+    const result = await buildDemo(args.out ? path.resolve(args.out) : undefined);
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  throw new Error(`Unknown command "${command}".`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});