Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Fixius50/WorlBuilding-Writting-App/llms.txt

Use this file to discover all available pages before exploring further.

The Maps module brings your world’s geography to life as an interactive, annotatable canvas. You can work with a real image of your hand-drawn map, reference an image hosted online, or start from a blank canvas — then layer on polygons, markers, lines, and annotations using a full drawing toolkit powered by MapLibre GL and Deck.gl. Map metadata (markers, layers, connections) is stored locally in SQLite WASM via the entity’s contenido_json field, while the image assets themselves are managed by the Java auxiliary backend.
The Java auxiliary backend must be running to upload a new map image, paste a URL, or create a blank canvas. If the backend is offline, the map creation flow will be unavailable. Existing maps with already-stored assets continue to render normally without the backend.

​
Creating a Map

Every map in Chronos Atlas begins by establishing its base image asset. There are three ways to create a new map, each backed by a dedicated backend endpoint:
1

Upload an image file

Choose an image from your local filesystem (PNG, JPEG, WebP). The frontend sends it to the backend as a multipart upload.
POST /mapeditor/assets/{projectName}/upload
Form params: name (map display name), file (the image file). The backend’s MapAssetProcessor writes the file to the maps_assets/ directory on disk and returns a MapAsset object with the stored filename.
2

Paste an image URL

Provide a publicly accessible image URL. The backend fetches and stores the remote image server-side.
POST /mapeditor/assets/{projectName}/upload-url
Form params: name (map display name), url (the remote image URL). Useful for referencing maps you’ve uploaded to an image host or CDN.
3

Create a blank canvas

Skip the image entirely and start drawing on a white canvas.
POST /mapeditor/assets/{projectName}/blank
Form params: name (map display name). The backend’s MapAssetProcessor.createBlankCanvas generates a blank image file and stores it in maps_assets/, returning the same MapAsset structure as the other two methods.
Once the asset is registered, the frontend calls MapUseCase.createMap to persist the new map as an Entidad of type MAPA in the local SQLite database, storing the image URL returned by the backend in the imagen_url field.

​
Map Editor

After opening a map, the full Map Editor provides a layered drawing environment built on two rendering technologies working in tandem:
  • MapLibre GL — renders the base layer (the uploaded or blank image) with smooth pan and zoom controls. The base layer is configured as an image source at coordinates that span the full canvas extent.
  • Deck.gl editable layers — sit above the MapLibre base and handle all interactive drawing. Polygons, polylines, and point markers are drawn as GeoJSON Feature objects collected inside a GeoFeatureCollection.
The MapEditor toolbar exposes the following drawing tools:
ToolDescription
PolygonClick to place vertices; close the shape to create a filled territory region.
MarkerClick to place a MapMarker at a coordinate, optionally labeled and linked to an entity.
LineClick to draw a MapConnection between two points; supports dashed lines and custom colors.
Select / MoveClick any drawn feature to select and reposition it.
EraserRemove a selected feature from the canvas.
The full drawing state — layers, markers, connections, zoom level, and center coordinates — is serialized as a MapAttributes JSON object and saved to the entity’s contenido_json field via MapUseCase.updateMap.

​
Map Data Types

The maps.ts domain file defines the core types used throughout the Maps module: 
export interface MapMarker {
  id: string;
  x?: number;
  y?: number;
  lng?: number;
  lat?: number;
  label?: string;
  description?: string;
  type?: string;
  entityId?: number | string | null;
  layerId?: string;
  targetLevelId?: string | null;
}

export interface MapConnection {
  id: string;
  sourceId: string;
  targetId: string;
  label?: string;
  type?: string;
  weight?: number;
  layerId?: string;
  color?: string;
  dashed?: boolean;
}

export interface MapLayer {
  id: string;
  name: string;
  visible: boolean;
  opacity: number;
  type: "base" | "image" | "vector" | "spray" | "markers" | string;
  url?: string;
  color?: string;
  featureType?: "line" | "polygon" | "point";
  attribution?: string;
}
The AtlasAttributes type extends MapAttributes with additional fields for the multi-level Atlas drawing mode, including levels, canvasStates, levelBgImages, and annotations.

​
Map Atlas Sidebar

The left sidebar of the Maps module is the Map Atlas, a panel that lists every map belonging to the current project. It mirrors the folder-tree pattern used in the World Bible: maps are grouped by their carpeta_id association, and a search box at the top filters the list by name in real time. Clicking any entry in the Atlas sidebar loads that map into the editor area and deselects the previous one cleanly.

​
Territory Linking

Drawn polygon territories on a map can be linked to Territory entities (type lugar) in the World Bible. Each MapMarker carries an optional entityId field that stores the ID of the corresponding Entidad. When a marker or polygon region has an entityId set, clicking it in the editor surfaces a quick-link button that navigates directly to that entity’s page in the World Bible, keeping geography and lore tightly connected. The relationship is bidirectional in intent: Territory entities in the World Bible can reference a map region, while the map region references back to the entity, allowing the same piece of geography to be documented in prose (World Bible) and visualised spatially (Maps) without duplication.

​
Asset Storage

Map image assets are stored server-side in the maps_assets/ directory managed by the Java backend — they are not placed in the browser’s OPFS. The backend uses the naming convention {projectName}_{fileName} when writing files to disk. A stored asset can be retrieved at any time via: 
GET /mapeditor/assets/{projectName}/download/{fileName}
The response is streamed as application/octet-stream with a Content-Disposition attachment header. The OPFS database holds only the URL reference (imagen_url) to the backend-served asset, keeping binary image data out of the browser’s local storage.

Build docs developers (and LLMs) love

Get started for freeTalk to us