DEV Community

Seven Yu
Seven Yu

Posted on Fully Autonomous

How I Turned a Website into a Seeded 3D Map

A personal website often starts as a list: tools, side projects, articles, and links to other places. I wanted mine to feel more like a place you could explore.

That experiment became Yahaha, a paper-like 3D world where categories are towns and links are buildings. Later, I extracted the map engine and the workflow into site-to-map, an agent skill for turning other link-heavy sites into maps.

The Yahaha map overview

The interesting part wasn't making a miniature house. It was figuring out how to turn an ordinary site's structure into a world that remains navigable, varied, and reproducible.

The pipeline: from links to landmarks

The workflow has four distinct stages:

  1. Extract headings, descriptions, and links from the source page.
  2. Plan towns and landmarks, then describe them in site.json.
  3. Generate the terrain and render the scene with three.js.
  4. Build the page and inspect screenshots of the overview and towns.

The distinction between extraction and planning matters. The extractor collects evidence; it does not understand every website or automatically decide what a link means. The agent uses the extracted structure and the skill's rules to group items, select shapes, and write the configuration. A person can edit that configuration afterward.

1. Read the site without inventing its contents

The extractor uses Playwright to load the page, then walks the DOM looking for headings, paragraphs, and anchors. It groups each link under the nearest preceding heading, records a short section description, and keeps same-origin URLs relative so the resulting map can work on a preview host or another domain.

If browser extraction fails, it falls back to fetching HTML and parsing it with jsdom. That fallback cannot see content created only after client-side JavaScript runs. Even the rendered pass is primarily link-oriented: a site that presents its content as buttons or application state may need manual inspection.

That limitation is intentional to acknowledge: a scraper can tell us what it found, not what it missed. The workflow asks the agent to inspect thin results and use real source descriptions rather than inventing them.

2. Make a small, explicit world model

The intermediate file is the contract between content and rendering. A simplified example looks like this:

{
  "site": {
    "brand": "Example",
    "lang": "en",
    "copyright": { "owner": "Example" }
  },
  "world": { "seed": "example-v1", "type": "coast" },
  "cities": [
    {
      "id": "tools",
      "slot": "center",
      "name": "Tool Town",
      "role": "Tools",
      "items": [
        { "name": "IP checker", "url": "/ip", "kind": "radio" },
        { "name": "Reading list", "url": "/reading", "kind": "library" }
      ]
    },
    {
      "id": "projects",
      "slot": "south",
      "name": "Workshop",
      "role": "Projects",
      "items": [
        { "name": "Source code", "url": "https://github.com/example", "kind": "school" }
      ]
    },
    {
      "id": "contact",
      "slot": "east",
      "name": "Market Square",
      "role": "Contact",
      "items": [
        { "name": "Email", "url": "mailto:hello@example.com", "kind": "dovecote" }
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

A town's slot is a role, not an exact coordinate. The generator decides where to put it. The workflow usually targets three to nine towns, with up to nine landmark buildings per town; additional links can remain clickable as props outside the town. That keeps a dense source page from turning into a wall of identical houses without silently dropping links.

3. A seed gives the map a memory

A map needs variety, but it also needs stability. If a visitor refreshes the page and the coastline moves, navigation stops feeling like navigation.

The world generator hashes a seed and uses a deterministic pseudorandom generator to choose features. It supports five broad land types: coast, two coasts, island, gulf, and lakeland. The seed influences the terrain and layout; the town roles and available space constrain placement.

A useful detail is the special seed {domain}. Yahaha is served from four domains using the same site data, but each domain produces a different landscape. The links stay the same while the geography changes.

Changing a seed is an editorial choice, not merely a color option: it can move towns and reshape the world. The skill therefore recommends choosing a seed and writing it into the configuration once the layout looks right. With the default fixed town size, adding a building does not resize the town and reshuffle the land; the optional fit mode packs towns more tightly but can move the layout as item counts change.

4. Prevent rivers from becoming real-estate problems

One early visual failure was a house sitting in a river. The tempting fix would have been to move a few river control points, but a segment between two safe points can still cut through a town.

The current generator treats each town as a padded circular footprint. It checks the entire river path against those footprints. If the initial route intersects one, it builds a visibility graph from candidate points around the obstacles and finds a clear route between the endpoints. It then tries to round the corners, accepting the smoothed result only if all of its segments still clear the same footprints.

This is a deliberately approximate model: the obstacle is a padded circle, not a detailed building collision mesh. But it solves the important layout problem at world-generation time and keeps the result deterministic.

Roads start from a different constraint: towns should be connected. The generator builds a spanning tree between town positions and may add an extra connection and lanes leaving the map. The rendered roads then connect into each town's local streets; water crossings can become bridges.

5. Variety is more than changing roof colors

A town full of different-colored copies of the same tower still reads as a town full of towers. The building catalogue therefore records silhouette families as well as individual kinds.

The agent can choose an explicit kind that fits the link: for example, a radio-shaped landmark for a network tool or a library for a reading collection. When a kind is omitted, the engine assigns one deterministically while balancing silhouettes. It does not pretend to infer the link's meaning. Explicit choices are preserved.

The builder also warns when a town repeats one kind or silhouette too heavily. That's a prompt to inspect the result, not an automatic rewrite: visual variety should not turn a meaningful landmark into a random object.

6. Render the world, but keep it usable

The engine builds the scene in three.js, with low-poly terrain, buildings, trees, lighting, and ink-like outlines. Time of day follows the visitor's local clock by default; lighting and interface colors refresh as the day changes.

The labels are HTML rather than text baked into the WebGL scene. They stay sharp and accessible, while pointer events pass through to the map controls. The engine checks visible label rectangles when resolving hover or click, so a label can still select a landmark without blocking drag and zoom.

Desktop layouts can show a larger information panel. Phones and tablets use a compact selection bubble, and the city menu provides a way to jump between towns without a lot of dragging. A no-JavaScript link list is included in the generated page; the interactive map itself needs WebGL.

7. A map is finished when someone has looked at it

The build script validates the configuration, warns about repetitive silhouettes, and writes a standalone page plus its engine files. The check script serves that output over HTTP, opens it with Playwright, captures an overview and each town, and reports page errors and labels hidden by overlap.

node scripts/extract.mjs https://example.com extract.json
# Review the extraction and write site.json
node scripts/build.mjs site.json out/
node scripts/check.mjs out/
Enter fullscreen mode Exit fullscreen mode

A green script run is not the same thing as a good map. I still need to look at the screenshots: are the towns distinguishable, are the labels readable, and does a landmark make sense for its link? The same goes for testing the actual links and smaller-screen interactions.

The result is a mix of authored decisions and procedural generation. The source site supplies the facts, the configuration supplies the meaning, and the seed supplies a landscape that can be revisited.

Try the map: https://yahaha.net/

Source and skill: https://github.com/dofy/site-to-map

If you've built a procedural scene around real content, I'd love to hear how you balance deterministic layout with the need to keep related things readable and close together.

Top comments (0)