Skip to content

development.md

Latest commit

 

History

History
100 lines (72 loc) · 4.16 KB

development.md

File metadata and controls

100 lines (72 loc) · 4.16 KB
Raw

Development

Requirements

  • Python 3 for the local HTTP server and the catalog generator.
  • A browser with Canvas, typed-array, <dialog>, file, and local-storage support.
  • Git for source control.

No JavaScript package installation or build command is required.

Start the editor

Run the HTTP server from the repository root:

python3 -m http.server 8000

Open http://127.0.0.1:8000/map-builder/. Serving only the map-builder directory is insufficient, because item and monster images resolve through parent directories.

Supply an asset tree

The repository distributes no artwork. Populate these directories locally before expecting thumbnails to render:

  • extractors/extracted/items/sprites/<id>.png
  • sprites/gen<n>/<folder>/normal/icon.png

Both paths are excluded by .gitignore, together with every other image extension and the generated catalog. Never re-include them; the published repository must stay free of third-party artwork and metadata.

A fresh clone has no catalog. Run the generator once before serving the editor, otherwise startup fails on the missing map-builder/catalog.json.

Rebuild the catalog

Run the generator after modifying either input. Both inputs live in the local asset tree and are not tracked:

  • extractors/extracted/items/manifest.json
  • sprites/index.json
python3 extractors/build_builder_catalog.py

The command rewrites map-builder/catalog.json and reports item, monster, and category counts. Treat the generated file as data; do not reformat it manually.

Implementation conventions

  • Keep the runtime dependency-free unless a documented architectural change is approved.
  • Keep the runtime free of source comments; express intent through naming and structure.
  • Preserve row-major indexing across arrays and exported grids.
  • Keep item flag values synchronized between the Python generator and the browser runtime.
  • Treat map format changes as schema changes and increment the exported version.
  • Maintain import compatibility when practical.
  • Resolve runtime assets through repository-relative paths.
  • Avoid embedding generated catalogs or binary sprites in documentation.

Manual verification

After a runtime or catalog change:

  1. Start the local server and load the editor without console errors.
  2. Create a map from each template.
  3. Exercise every paint shape on the ground and object layers.
  4. Place player and monster spawns and run the map health check.
  5. Verify undo and redo across tiles, marks, selections, and spawns.
  6. Export detailed, compact, and combined documents.
  7. Import each exported document and confirm an equivalent map.
  8. Reload the page and confirm autosave restoration.

Troubleshooting

Symptom Cause Resolution
Blank asset library The catalog was requested from disk or from the wrong root. Serve the repository root over HTTP.
Empty item thumbnails No local asset tree is present, which is the default for a fresh clone. Populate extractors/extracted/items/sprites/.
Empty creature icons No local asset tree is present, or the generation or folder value is stale. Populate sprites/gen*/, then rebuild the catalog.
Header reports a failed autosave The document exceeds the local-storage quota. Save a map file and reduce map dimensions.
The maps/ folder is requested repeatedly The browser revoked the stored directory permission. Reauthorize the directory, or use the download fallback.
Interface text falls back to English A locale catalog failed to load or is invalid JSON. Validate locales/<code>.json and reload.

Source-control scope

The repository tracks only source code, documentation, locale catalogs, and the generated runtime catalog. .gitignore is an allowlist: it starts by excluding everything, re-includes tracked paths by hand, and then denies every image extension unconditionally. Game clients, server data, archives, animation strips, and all artwork remain local.

Commit messages and collaboration practices are defined in Commit conventions.

Locale catalog structure, validation requirements, and translation rules are defined in Localization.