Map Builder

Map Builder is a browser-based tile map editor for grid overworlds. It provides two paintable layers, navigation metadata, creature spawn placement, connectivity validation, local autosave, versioned map files, and JSON import and export.

The project is an unofficial, non-commercial fan tool written as a personal development exercise. Its tile grammar follows classic top-down MMORPG tilesets, and its spawn model follows the first four generations of monster-taming games. It is not affiliated with any rights holder. See NOTICE.

The application is a self-contained HTML document written in vanilla JavaScript against the Canvas API. It requires no package manager, build step, backend service, or user account.

Capabilities

• Browse and search a catalog of 32,317 items and 417 creatures.
• Paint independent ground and object layers.
• Apply collision, water, missile-blocking, and pathfinding-blocking marks.
• Place one player spawn and any number of creature spawns.
• Use freehand, rectangle, outline, line, and flood-fill operations.
• Move, duplicate, or clear rectangular selections across both layers.
• Inspect map connectivity and spawn validity before export.
• Undo or redo up to 80 committed strokes.
• Persist the active map in browser local storage.
• Write numbered map revisions to a user-authorized maps/ directory.
• Switch between English, Spanish, and Portuguese without reloading.
• Import legacy documents and export version 4 JSON documents.

Requirements

• Python 3, used for the local HTTP server and the catalog generator.
• A browser providing Canvas, typed arrays, <dialog>, and local storage.
• The File System Access API is optional and enables direct folder writes.

No game content is included

This repository contains source code only. It ships no artwork and no item or creature metadata. Every image extension and the generated catalog are excluded from version control. The editor resolves both from a local asset tree that you supply:

Path	Contents	Tracked
extractors/extracted/items/manifest.json	Item metadata used by the generator.	No
extractors/extracted/items/sprites/<id>.png	One image per item ID.	No
sprites/index.json	Creature index used by the generator.	No
sprites/gen<n>/<folder>/normal/icon.png	One icon per creature.	No
map-builder/catalog.json	Runtime catalog produced by the generator.	No

Point the generator at a dataset you have the right to use. Nothing in this repository depends on any particular game's files.

Local execution

Build the runtime catalog once, then serve the repository root, because the editor resolves catalog and sprite files through relative URLs:

python3 extractors/build_builder_catalog.py
python3 -m http.server 8000

Open http://127.0.0.1:8000/map-builder/ in a browser. Opening the HTML file from disk is unsupported, because browsers reject local fetch requests. The editor requires map-builder/catalog.json to start; without an asset tree it has no catalog to load.

Repository structure

Path	Purpose
index.html	Redirects the repository root to the editor.
map-builder/index.html	Contains the editor interface and runtime logic.
locales/	Contains the English, Spanish, and Portuguese catalogs.
extractors/build_builder_catalog.py	Rebuilds the runtime catalog.
docs/	Contains user, format, architecture, and process documentation.

Catalog generation

The generator reads an item manifest and a creature index from the local asset tree and writes map-builder/catalog.json, which is untracked:

python3 extractors/build_builder_catalog.py

It retains named and unnamed items, encodes item flags as a bitmask, assigns one of 19 palette categories, and sorts items by numeric identifier. Records are emitted as positional arrays described by the fields object, which the runtime expands into lookup tables during startup.

Documentation

Document	Contents
User guide	Tools, shortcuts, validation, import, and export.
Map document format	Schema, mark bits, versioning, and compatibility.
Architecture	State model, rendering, persistence, and catalog pipeline.
Development	Environment, conventions, verification, and troubleshooting.
Localization	Locale catalogs, runtime behavior, and validation.
Commit conventions	Commit, branch, and pull-request standards.

License

Source code, documentation, and configuration are released under the MIT License. That grant does not extend to third-party game content loaded at runtime; see NOTICE for the full statement.