Mapper

Generated from smudgy v0.3.5 (smudgy-mapper.d.ts @ bd98f888f8b0). Index: scriptref.

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

declare const mapper: Mapper;

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

interface Mapper {
    createArea(name: string): 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;
    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;
    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>;
}

The map API for the current session (each session has its own). Changes 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).
• 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.
• 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.

declare class Area {
    private constructor();
    readonly id: AreaId;
    readonly name: string;
    readonly room_numbers: RoomNumber[];
    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.

• 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 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.

• 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;
    readonly style: ExitStyle;
    readonly color: 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.
• color — A CSS color string, or null for the default.

interface CreateRoomParams {
    title?: string;
    description?: string;
    level?: number;
    x?: number;
    y?: number;
    color?: 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.

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;
    style?: ExitStyle;
    color?: string;
}

Fields accepted when creating an exit (mapper.createRoomExit). Only from_direction is required. Careful: style and color are accepted for symmetry but ignored on creation; set them afterwards with mapper.setRoomExit.

• style — Accepted for parity but ignored on creation; use setRoomExit to set it.
• color — Accepted for parity but ignored on creation; use setRoomExit to set it.

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;
    style?: ExitStyle;
    color?: string;
}

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

• color — A CSS color string.

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 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 ExitStyle = "Normal" | "Dashed" | "Dotted" | "Meandering" | "Stub";

How an exit is drawn on the map.

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:core — Sessions & output · smudgy:core — Lines & buffer · smudgy:core — Events · smudgy:core — Automations · smudgy:core — Saved automations · smudgy:core — Panes · smudgy:widgets · smudgy:params