Work with maps

Import mapper from smudgy:core. Map types such as Area and Room are available globally to TypeScript.

import { mapper } from "smudgy:core";
 
const area = await mapper.createArea("Tutorial");
const square = mapper.createRoom(area, {
  title: "Town Square",
  x: 0,
  y: 0,
});
 
mapper.setCurrentLocation(area.id, square);

Persistent changes update the local cache immediately and sync to the cloud in the background. An ephemeral area belongs only to the current session and is discarded when the session closes.

AreaId, ExitId, LabelId, and ShapeId are tuple-shaped identifiers. Pass values returned by the mapper back unchanged; do not construct or inspect them. A room number is meaningful only within its area.

Use area.room(number) to obtain a room. The room exposes its exits, tags, custom data, and update helper. Mapper methods create and delete rooms, exits, labels, and shapes.

For server-provided room numbers, bind an externalId. findRoomByExternalId() can then connect GMCP or MSDP room data to the correct mapped room.

Scripts create and update exits, which describe traversal from one room: destination, direction, command, weight, and open or locked state. Every exit belongs to a displayed connection. When a new exit is the unique direction-compatible reciprocal of an existing one, Smudgy pairs the two exits onto the same connection; ambiguous or contradictory exits remain separate one-way connections.

Connection geometry, dash, color, and thickness are not exit fields. The current script contract does not expose those appearance properties for editing. Do not add old style or color fields to exit arguments, and do not modify the opaque AreaJson export to reach connection data.

getPathBetweenRooms() returns the least-cost sequence of area and room pairs. Exit weights determine cost. The nearest-room helpers can search by tag or destination area before you request the path itself.

exportArea() produces an opaque AreaJson value. Import related areas together with importAreas() so exits between them can be relinked. Packages that install bundled maps repeatedly can use importAreasIfAbsent() to skip names already resident in the mapper, including disabled maps and maps assigned to other server entries.

Treat an exported value as a file to store and pass back, not as a schema for package code. Smudgy may change its internal map document when connection or rendering features change.

The importer accepts older supported documents and migrates them before saving. A document created by a newer, unsupported client is rejected. Smudgy validates every document in an importAreas() call before writing any of them, so one invalid or unsupported document rejects the whole batch rather than leaving a partial set.

Imported areas receive fresh identities. Cross-area destinations within the same batch are remapped to those new identities; a destination outside the imported batch is dropped. Export and import related areas together when those links must survive.

See the Mapper API reference for the full surface.