Mapper

Generated from smudgy v0.4.2-dev (smudgy-mapper.d.ts @ 1a1183a3a230). Index: scriptref.

The map API: import { mapper } from "smudgy:core". The map types (Area, Room, …) need no import.

For common workflows and coordinate conventions, see Work with maps.

interface Mapper {
    createArea(name: string, options?: CreateAreaOptions): Promise<Area>;
    setCurrentLocation(areaId: AreaId, roomNumber?: RoomNumber): void;
    getCurrentLocation(): { area: AreaId; room?: RoomNumber } | undefined;
    readonly areas: Area[];
    getAreaById(id: AreaId): Area;
    getPathBetweenRooms(
        fromAreaId: AreaId,
        fromRoomNumber: RoomNumber,
        toAreaId: AreaId,
        toRoomNumber: RoomNumber,
    ): [AreaId, RoomNumber][];
    listRoomsByTitleAndDescription(title: string, description: string): (Room | undefined)[];
    listRoomsByTitleDescriptionAndVisibleExits(
        title: string,
        description: string,
        visibleExitDirections: string[],
    ): (Room | undefined)[];
    renameArea(area: Area | AreaId, name: string): void;
    deleteArea(area: Area | AreaId): void;
    setRoomTitle(area: Area | AreaId, room: Room | RoomNumber, title: string): void;
    setRoomDescription(area: Area | AreaId, room: Room | RoomNumber, description: string): void;
    setRoomColor(area: Area | AreaId, room: Room | RoomNumber, color: string): void;
    setRoomLevel(area: Area | AreaId, room: Room | RoomNumber, level: number): void;
    setRoomX(area: Area | AreaId, room: Room | RoomNumber, x: number): void;
    setRoomY(area: Area | AreaId, room: Room | RoomNumber, y: number): void;
    setRoomProperty(area: Area | AreaId, room: Room | RoomNumber, name: string, value: string): void;
    setAreaProperty(area: Area | AreaId, name: string, value: string): void;
    addRoomTag(area: Area | AreaId, room: Room | RoomNumber, tag: string): void;
    removeRoomTag(area: Area | AreaId, room: Room | RoomNumber, tag: string): void;
    findNearestRoomWithTag(from: Room, tag: string): Room | undefined;
    findNearestRoomWithTags(
        from: Room,
        filter: { all?: string[]; none?: string[] },
    ): Room | undefined;
    findNearestRoomInArea(from: Room, area: Area | AreaId): Room | undefined;
    findRoomByExternalId(externalId: string): Room | undefined;
    rescueRoomByExternalId(externalId: string): boolean;
    setRoomExternalId(area: Area | AreaId, room: Room | RoomNumber, externalId: string): void;
    createRoom(area: Area | AreaId, params: CreateRoomParams): RoomNumber;
    updateRoom(area: Area | AreaId, room: Room | RoomNumber, fields: UpdateRoomParams): void;
    updateRooms(area: Area | AreaId, updates: [RoomNumber, UpdateRoomParams][]): void;
    createRoomExit(area: Area | AreaId, room: Room | RoomNumber, exit: ExitArgs): Promise<ExitId>;
    setRoomExit(area: Area | AreaId, room: Room | RoomNumber, exitId: ExitId, exit: ExitUpdates): void;
    deleteRoom(area: Area | AreaId, room: Room | RoomNumber): void;
    deleteRoomExit(area: Area | AreaId, room: Room | RoomNumber, exitId: ExitId): void;
    createLabel(area: Area | AreaId, label: LabelArgs): Promise<LabelId>;
    createShape(area: Area | AreaId, shape: ShapeArgs): Promise<ShapeId>;
    deleteLabel(area: Area | AreaId, labelId: LabelId): void;
    deleteShape(area: Area | AreaId, shapeId: ShapeId): void;
    setLabel(area: Area | AreaId, labelId: LabelId, updates: LabelUpdates): void;
    setShape(area: Area | AreaId, shapeId: ShapeId, updates: ShapeUpdates): void;
    exportArea(area: Area | AreaId): Promise<AreaJson>;
    importAreas(areas: AreaJson[]): Promise<AreaId[]>;
    importArea(area: AreaJson): Promise<AreaId>;
    importAreasIfAbsent(areas: AreaJson[]): Promise<AreasImportedIfAbsent>;
}

The map API for the current session. Each session has its own current location; changes to persistent areas sync to the cloud in the background.

• createArea — Create a new area and return its handle.
• setCurrentLocation — Set the current map location (the per-session “you are here” marker).
• getCurrentLocation — The current map location, or undefined if none is set. room is absent when the location names an area without a specific room.
• areas — All active areas (areas marked inactive are excluded).
• getPathBetweenRooms — The cheapest route between two rooms, as a list of [areaId, roomNumber] steps (each exit's weight is its cost).
• deleteArea — Delete an area and everything in it.
• setRoomColor — Set a room's color to a CSS color string.
• setRoomProperty — Set a custom room property (string key/value).
• setAreaProperty — Set a custom area property (string key/value); the write counterpart of area.data(key). Pass an empty value to clear it.
• addRoomTag — Add a case-insensitive tag to a room (normalized to UPPERCASE; re-adding is a no-op).
• removeRoomTag — Remove a tag from a room (case-insensitive).
• findNearestRoomWithTag — The nearest reachable room carrying tag (case-insensitive) from from, by the same weighted search as getPathBetweenRooms (the start room counts if it carries the tag), or undefined if none is reachable. Path to it with getPathBetweenRooms.
• findNearestRoomWithTags — The nearest reachable room that carries every tag in all and none of the tags in none (all case-insensitive); undefined if no such room is reachable or the filter is empty. Used by multi-tag speedwalks like \inn.peace and \!peace.guild.
• findNearestRoomInArea — The nearest reachable room belonging to area from from, by the same weighted search as getPathBetweenRooms (from itself counts if it is already in the area, and naming the area reaches it even when it is marked inactive), or undefined if no room of the area is reachable. Path to it with getPathBetweenRooms.
• findRoomByExternalId — The room bound to a server-global room id (the room number games send over GMCP or MSDP), or undefined if no loaded room carries it. When the same id is bound in more than one area, one match is returned (rooms in your own maps win over shared ones).
• rescueRoomByExternalId — Reports whether a room with this server-global id is already mapped for a different server. When it is, the player is offered the chance to show that map here too, and this returns true, so a map drawn as you explore knows the room is accounted for and need not be recreated. Returns false when the id belongs to no other server's map.
• setRoomExternalId — Bind (or, with an empty string, clear) a room's server-global room id.
• createRoom — Create a room and return its new room number.
• updateRoom — Update multiple fields of a room in one cache update; only present fields change.
• updateRooms — Batch-update many rooms of one area in a single cache update.
• createRoomExit — Create an exit on a room and return its new id.
• setRoomExit — Update an existing exit. Returns nothing.
• deleteRoom — Delete a room.
• deleteRoomExit — Delete an exit from a room.
• createLabel — Add a text label to an area and return its new id.
• createShape — Add a graphical shape to an area and return its new id.
• deleteLabel — Delete a label from an area.
• deleteShape — Delete a shape from an area.
• setLabel — Update an existing label; only present fields change.
• setShape — Update an existing shape; only present fields change.
• exportArea — Export an area as a portable AreaJson. Requires copy rights on the area.
• importAreas — Import exported areas as new local areas (fresh ids). Exits between areas in the set are relinked to the new copies; exits pointing outside the set are kept but left unlinked. Returns the new area ids. Prefer this one-call form for multi-area imports.
• importArea — Import one exported area as a new local area; returns its id.
• importAreasIfAbsent — Import exported areas, skipping any whose name is already resident in the mapper. Shared maps, deactivated maps, and maps assigned to other server entries count too. Waits for the session's maps to finish loading first, so it is safe to call as a package starts, on every start, without creating duplicates. Returns the ids of the areas imported and the names skipped.

declare const mapper: Mapper;

The current session's map API, as a global. Deprecated: import mapper from smudgy:core instead.

declare class Area {
    private constructor();
    readonly id: AreaId;
    readonly name: string;
    readonly room_numbers: RoomNumber[];
    readonly isEphemeral: boolean;
    readonly next_room_number: RoomNumber;
    room(roomNumber: number): Room | undefined;
    data(key: string): string | undefined;
    readonly labels: Label[];
    readonly shapes: Shape[];
    toString(): string;
}

A map area. You get areas from the mapper (mapper.areas, mapper.getAreaById), never by constructing one; the global Area class exists so checks like area instanceof Area work.

• isEphemeral — Whether this is a session map: it lives only for this session and is discarded when the session closes. Save it with mapper.exportArea + mapper.importAreas to keep it.
• next_room_number — The next unused room number in this area.
• room — The room with this number, or undefined.
• data — Read a custom area property by key (or undefined if unset).
• labels — This area's text labels.
• shapes — This area's graphical shapes.

interface Room {
    readonly room_number: RoomNumber;
    readonly area_id: AreaId;
    readonly title: string;
    readonly externalId: string | undefined;
    readonly description: string;
    readonly level: number;
    readonly x: number;
    readonly y: number;
    readonly color: string;
    readonly exits: Exit[];
    data(key: string): string | undefined;
    readonly tags: string[];
    hasTag(tag: string): boolean;
    update(fields: UpdateRoomParams): void;
    toString(): string;
}

A room read from the map. Obtain one via area.room(n) or the listRooms* helpers.

• externalId — The server's own id for this room (the room number games send over GMCP or MSDP), or undefined if none is bound. Bind one at creation (externalId in the room fields) or with mapper.setRoomExternalId.
• color — A CSS color string.
• data — Read a custom room property by key (or undefined if unset).
• tags — This room's tags, normalized to UPPERCASE and sorted.
• hasTag — Whether this room carries tag (case-insensitive).
• update — Update multiple fields of this room in one cache update; only present fields change.

interface Exit {
    readonly id: ExitId;
    readonly from_direction: ExitDirection;
    readonly from_area_id: AreaId;
    readonly from_room_number: RoomNumber;
    readonly to_direction: ExitDirection | null;
    readonly to_area_id: AreaId | null;
    readonly to_room_number: RoomNumber | null;
    readonly is_hidden: boolean;
    readonly is_closed: boolean;
    readonly is_locked: boolean;
    readonly weight: number;
    readonly command: string | null;
}

One exit read back from a room (room.exits). Optional links are present but null when unset (not omitted).

• weight — Pathfinding cost.
• command — The command sent to traverse this exit, or null to use from_direction.

interface CreateAreaOptions {
    ephemeral?: boolean;
}

Options for Mapper.createArea.

• ephemeral — Create a session map: it lives only for this session, is never saved or synced, and is discarded when the session closes. Use this for maps built automatically from server data.

interface CreateRoomParams {
    title?: string;
    description?: string;
    level?: number;
    x?: number;
    y?: number;
    color?: string;
    externalId?: string;
}

Fields accepted when creating a room (mapper.createRoom). Any omitted field takes its default.

• level — Map level / z-layer.
• color — A CSS color string.
• externalId — The server's own id for this room (the room number games send over GMCP or MSDP). An empty string clears an existing binding.

type UpdateRoomParams = CreateRoomParams;

Fields accepted when updating a room (mapper.updateRoom/Room.update): the same set as creation. Any omitted field is left unchanged.

interface ExitArgs {
    from_direction: ExitDirection;
    to_direction?: ExitDirection;
    to_area_id?: AreaId;
    to_room_number?: RoomNumber;
    is_hidden?: boolean;
    is_closed?: boolean;
    is_locked?: boolean;
    weight?: number;
    command?: string;
}

Fields accepted when creating an exit (mapper.createRoomExit). Only from_direction is required. Visual appearance (routing, dash, color, thickness) lives on the shared Connection, not the exit.

interface ExitUpdates {
    from_direction?: ExitDirection;
    to_direction?: ExitDirection;
    to_area_id?: AreaId;
    to_room_number?: RoomNumber;
    is_hidden?: boolean;
    is_closed?: boolean;
    is_locked?: boolean;
    weight?: number;
    command?: string;
}

Fields accepted when updating an exit (mapper.setRoomExit). Any omitted field is left unchanged.

type AreaJson = Record<string, unknown>;

A portable area export, produced by Mapper.exportArea and consumed by Mapper.importArea/Mapper.importAreas. Treat it as opaque: export it, store it, import it back, but do not depend on its internal shape.

interface AreasImportedIfAbsent {
    readonly added: AreaId[];
    readonly skipped: string[];
}

The outcome of Mapper.importAreasIfAbsent.

• added — Ids of the areas imported by this call.
• skipped — Names skipped because a resident map already has that name.

interface Label {
    readonly id: LabelId;
    readonly level: number;
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly horizontal_alignment: LabelHorizontalAlign;
    readonly vertical_alignment: LabelVerticalAlign;
    readonly text: string;
    readonly color: string;
    readonly background_color: string;
    readonly font_size: number;
    readonly font_weight: number;
}

A text label read back from an area (area.labels).

• level — Map level / z-layer.
• color — A CSS color string.
• background_color — A CSS color string for the background ("" for none).

interface LabelArgs {
    x: number;
    y: number;
    width: number;
    height: number;
    text: string;
    level?: number;
    horizontal_alignment?: LabelHorizontalAlign;
    vertical_alignment?: LabelVerticalAlign;
    color?: string;
    background_color?: string;
    font_size?: number;
    font_weight?: number;
}

Fields accepted when creating a label (mapper.createLabel). Position, size, and text are required; any omitted field takes its default.

• level — Map level / z-layer (default 0).
• horizontal_alignment — Text alignment (defaults: Center / Center).
• color — A CSS color string for the text (default "#ffffff").
• background_color — A CSS color string for the background; omit for none.
• font_size — Text size in px (default 16).
• font_weight — Text weight (default 400).

interface LabelUpdates {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    text?: string;
    level?: number;
    horizontal_alignment?: LabelHorizontalAlign;
    vertical_alignment?: LabelVerticalAlign;
    color?: string;
    background_color?: string;
    font_size?: number;
    font_weight?: number;
}

Fields accepted when updating a label (mapper.setLabel). Any omitted field is left unchanged.

• level — Map level / z-layer.
• color — A CSS color string for the text.
• background_color — A CSS color string for the background.

interface Shape {
    readonly id: ShapeId;
    readonly level: number;
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly background_color: string | null;
    readonly stroke_color: string | null;
    readonly shape_type: ShapeKind;
    readonly border_radius: number;
    readonly stroke_width: number;
}

A graphical shape read back from an area (area.shapes).

• level — Map level / z-layer.
• background_color — A CSS color string, or null for none.
• stroke_color — A CSS color string, or null for none.

interface ShapeArgs {
    x: number;
    y: number;
    width: number;
    height: number;
    level?: number;
    background_color?: string;
    stroke_color?: string;
    shape_type?: ShapeKind;
    border_radius?: number;
    stroke_width?: number;
}

Fields accepted when creating a shape (mapper.createShape). Position and size are required; any omitted field takes its default.

• level — Map level / z-layer (default 0).
• background_color — A CSS fill color; omit for none.
• stroke_color — A CSS stroke color; omit for none.
• shape_type — Shape kind (default "Rectangle").
• border_radius — Corner radius (default 0).
• stroke_width — Stroke width in px.

interface ShapeUpdates {
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    level?: number;
    background_color?: string;
    stroke_color?: string;
    shape_type?: ShapeKind;
    border_radius?: number;
    stroke_width?: number;
}

Fields accepted when updating a shape (mapper.setShape). Any omitted field is left unchanged.

• level — Map level / z-layer.
• background_color — A CSS fill color.
• stroke_color — A CSS stroke color.

type AreaId = readonly [number, number];

An area's identifier. Treat it as opaque: take it from one mapper call and pass it back to another, unchanged. Careful: this is not the same as the UUID string the map:room event delivers; the two are not interchangeable.

type RoomNumber = number;

A room number within an area (a 32-bit integer).

type ExitId = readonly [number, number];

An exit's identifier: a 2-element [hi, lo] pair, like AreaId. Opaque.

type LabelId = readonly [number, number];

A label's identifier: a 2-element [hi, lo] UUID pair, like AreaId. Opaque.

type ShapeId = readonly [number, number];

A shape's identifier: a 2-element [hi, lo] UUID pair, like AreaId. Opaque.

type ExitDirection =
| "North"
| "East"
| "South"
| "West"
| "Up"
| "Down"
| "Northeast"
| "Northwest"
| "Southeast"
| "Southwest"
| "In"
| "Out"
| "Special"
| "Other";

A compass/special exit direction (the canonical PascalCase names).

type LabelHorizontalAlign = "Left" | "Center" | "Right";

Horizontal alignment of a label's text.

type LabelVerticalAlign = "Top" | "Center" | "Bottom";

Vertical alignment of a label's text.

type ShapeKind = "Rectangle" | "RoundedRectangle";

A shape's kind.

Script API reference · ← smudgy:widgets — Canvas · smudgy:params → · Scripting manual