One tile.
Your own layers.

01 / START A TILE

A map independent of your scene.

The CLI creates an image map package with an example landscape. Replace the example with your own image and add child objects. Run from this workspace after corepack pnpm install.

pnpm threetopia slots --registry public/atlas/registry.json
pnpm threetopia create my-world --tile 1,-1 \
  --registry public/atlas/registry.json --connect SW
pnpm threetopia check my-world
pnpm threetopia preview my-world

Your playable scene remains separate. Every world declares a mandatory map.json, axial tile coordinates and six Wang edge signatures. Selecting a tile does not reserve it.

02 / IMAGES & LAYERS

A composition, not a flattened world.

Each tile owns its own landscape image. Every moving object is another transparent image inside that tile. Moving the parent carries its objects along; a child can animate independently within it. Do not paint neighbouring worlds, moving boats, airships or clouds into your landscape.

{
  "version": 2,
  "kind": "image-tile",
  "origin": "tile-centre",
  "radius": 400,
  "terrain": {
    "src": "assets/landscape.webp",
    "preview": "assets/landscape-overview.webp",
    "position": [0, -30],
    "size": [1040, 840],
    "anchor": [0.5, 0.58]
  },
  "components": [{
    "id": "harbour-boat",
    "label": "Harbour sailboat",
    "src": "assets/boat.webp",
    "position": [-15, 115],
    "size": [120, 80],
    "anchor": [0.5, 0.5],
    "order": 5,
    "animation": {
      "kind": "sail", "duration": 28,
      "travel": [35, 35], "rotate": 4, "delay": -6
    }
  }],
  "landmarks": [
    {"id": "harbour", "label": "Harbour", "position": [-70, 85]}
  ]
}

Use real alpha transparency in PNG, WebP or AVIF. Match the living-diorama camera, warm light from the upper left and shared shoreline palette. Keep the ocean outside the shore fringe transparent. Package image paths are relative to the map JSON and must stay inside the package.

Art coordinates are not metres. The tile itself remains a 400 m Wang hex. World centres and live player positions use u = 1.18x + 0.32z and v = −0.15x + 0.56z. The map is an illustrated overview; actual movement and collision use the playable world.

import { defineImageMap } from '@threetopia/world-map';
import { ImageAtlasRenderer } from '@threetopia/world-map/image-renderer';
import '@threetopia/world-map/image-renderer.css';

const map = defineImageMap(data);
const view = new ImageAtlasRenderer(element, registry, { onSelect, onError });
view.fit();
view.setOptions({ motion: true, creators: false });
// When removed: view.dispose();

In the registry, imageMap points to the tile JSON. The current four manifests live in public/map/tiles/. Open Layers on the map to hide individual objects or separate them visually from their landscape. These inspection settings are not saved edits.

03 / ANIMATION & LANDMARKS

Give each object its own motion.

Animation presets: float, sail, drift and petals. Each component has its own duration (4–180 seconds), travel (up to ±300 units per axis), rotation (±45°) and starting delay. Multiple objects can reuse one image file. No arbitrary scripts or shaders are accepted in map data.

The current map has four independent landscape images and eleven moving components. Airships belong to Punk, boats to their own harbour or lagoon tile, petals to Sakura and mist to its parent tile. Labels and landmarks are interactive HTML; they are not baked into the images.

Add a landmark with a stable ID, a label and a local image position. Landmark labels become visible when zoomed in and hide when they overlap. World labels remain available farther out.

04 / SHARED EDGES

Keep both sides connected.

Each complete world occupies one hex tile, 693 metres between opposite sides and 800 metres between opposite corners. Lagoon is the centre; the world expands around it. The six Wang signatures are ordered E, SE, SW, W, NW, NE.

Give adjoining images compatible low ground, vegetation and paths. Their visual coastal overlap does not replace the physical edge contract. Keep normal exploration free of drawn borders; use Tile edges to inspect the logical grid.

05 / PERFORMANCE

Load the map, not the game.

The current overview images, ocean and sprites total about 957 KiB. Individual detail images are 558–750 KiB and load on zoom. The renderer uses DOM images and CSS transforms: zero canvases, no WebGL context and no JavaScript animation loop.

Component animations pause in the minimap, in a hidden document, with Motion off or when reduced motion is requested. Distant views hide components and landmark labels. The minimap and full map reuse the same DOM tree. A large public world still needs spatial registry pagination.

Version 1 mesh data remains available for old geometry and seam validation, but the current map UI and new CLI previews use version 2 images.

06 / CLI REFERENCE

Validate and preview independently.

The packages are available in this workspace. There is no npm release or remote publishing service yet.

07 / PLACEMENT PROPOSALS

Grow around the centre.

1. Open the map and choose Build here.
2. Select an ocean tile and inspect its neighbours.
3. Copy the starter command or download a placement proposal.
4. Make the separate tile landscape, component images, map JSON and playable scene.
5. Agree new crossings with neighbours and validate both manifests.
6. Submit the package and proposal for integration.

Tile selection is shareable by URL. It is a proposal, not a reservation or publication.