Work with maps

Import mapper from smudgy:core. Map types such as Area and Room are available globally to TypeScript. If you need a runtime check, import the Area value too: import { mapper, Area } from "smudgy:core", then use area instanceof Area.

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, wei