Revision as of 06:37, 24 December 2024

Mapper Functions

These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the game you're playing. For a collection of pre-made scripts and general mapper talk, visit the mapper section of the forums.

To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:

mudlet = mudlet or {}; mudlet.mapper_script = true

addAreaName

areaID = addAreaName(areaName)

Adds a new area name and returns the new (positive) area ID for the new name. If the name already exists, older versions of Mudlet returned -1 though since 3.0 the code will return nil and an error message.

addCustomLine

addCustomLine(roomID, id_to, direction, style, color, arrow): See also: getCustomLines(), removeCustomLine()

Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.

Parameters

roomID:

Room ID to attach the custom line to.

id_to:

EITHER: a room Id number, of a room on same area who's x and y coordinates are used as the other end of a SINGLE segment custom line (it does NOT imply that is what the exit it represent goes to, just the location of the end of the line);

OR: a table of sets of THREE (x,y and z) coordinates in that order, x and y can be decimals, z is an integer (and must be present and be the same for all points on the line, though it is irrelevant to what is produced as the line is drawn on the same z-coordinate as the room that the line is attached to!)

direction: a string to associate the line with a valid exit direction, "n", "ne", "e", "se", "s", "sw", "w", "nw", "up", "down", "in" or "out" or a special exit (before Mudlet 3.17 this was case-sensitive and cardinal directions had to be uppercase).
style: a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.

how these look can be seen in the Map Legend section of the manual

color: a table of three integers between 0 and 255 as the custom line color as the red, green and blue components in that order.
arrow: a boolean which if true will set the custom line to have an arrow on the end of the last segment.

Available in Mudlet3.0+

Examples

-- create a line from roomid 1 to roomid 2
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)

addCustomLine(1, {{1, 2, 0}, {1, 4, 0}, {0, 5, 0}}, "N", "dash dot dot line", {128, 128, 0}, false)

The second custom exit will look like the below screenshot.

A bigger example that'll create a new area and the room in it:

local areaid = addAreaName("Custom Exit Playground")
local firstRoom = createRoomID()
addRoom(firstRoom, areaid)
setRoomCoordinates(firstRoom, 0, 0, 0)

local secondRoom = createRoomID()
addRoom(secondRoom, areaid)
setRoomCoordinates(secondRoom, 0, 5, 0)

-- make a special exit for this room, and a custom exit line
addSpecialExit(firstRoom, secondRoom, "climb Rope")
addCustomLine(firstRoom, {{1, 2, 0}, {1, 4, 0}, {0, 5, 0}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)

centerview(firstRoom)

This should result in a map with a custom exit looking something like the following.

addMapEvent

addMapEvent(uniquename, event name, parent, display name, arguments)

Adds a new entry to an existing mapper right-click entry. You can add one with addMapMenu. If there is no display name, it will default to the unique name (which otherwise isn't shown and is just used to differentiate this entry from others). event name is the Mudlet event that will be called when this is clicked on, and arguments will be passed to the handler function.

Example

addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite

addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")

The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.

addMapMenu("Room type")
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")

function onMapMarkSelectedRooms(event, markRoomType)
  local selectedRooms = getMapSelection()["rooms"]
  for i, val in ipairs(selectedRooms) do
    if markRoomType == "markRoomsAsDeathTrap" then
      local r, g, b = unpack(color_table.black)
      --death trap
      setRoomEnv(val, 300)
      --death traps Env
      setCustomEnvColor(300, r, g, b, 255)
      setRoomChar(val, "☠️")
      lockRoom(val, true)
    elseif markRoomType == "markRoomsAsOneRoom" then
      local r, g, b = unpack(color_table.LightCoral)
      --single-pass
      setRoomEnv(val, 301)
      --one room Env
      setCustomEnvColor(301, r, g, b, 255)
      setRoomChar(val, "🚹")
    end
  end
  updateMap()
end

registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")

This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"

addMapMenu

addMapMenu(uniquename, parent, display name)

Adds a new submenu to the right-click menu that opens when you right-click on the mapper. You can then add more submenus to it, or add entries with addMapEvent().

Example

-- This will create a menu named: Favorites.
addMapMenu("Favorites")

-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.
addMapMenu("Favorites1234343", "Favorites", "More Favorites")

addRoom

addRoom(roomID, areaID)

Creates a new room with the given room ID and area ID, returns true if the room was successfully created.

Parameters

roomID:

Room ID to set the room as, manually assigned or from createRoomID().

areaID:

Area ID to set the room in, as returned by getAreaTable() or equivalents.

Note: If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with createRoomID() and associating your room IDs with Mudlets via setRoomIDbyHash() and getRoomIDbyHash(). The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge. Note: Creating your own mapping script? Check out more information here.

addSpecialExit

addSpecialExit(roomIDFrom, roomIDTo, moveCommand)

Creates a one-way from one room to another, that will use the given command for going through them.

Example

-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command
addSpecialExit(1, 2, "pull rope")

Example in an alias:

-- sample alias pattern: ^spe (\d+) (.*?)$
-- currentroom is your current room ID in this example
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])
centerview(currentroom)

auditAreas

auditAreas()

Initiates a consistency check on the whole map: All rooms, areas, and their composition. This is also done automatically whenever you first open your map, so probably seldom necessary to do manually. Will output findings to screen and/or logfile for later review.

centerview

centerview (roomID)

Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.

clearAreaUserData

clearAreaUserData(areaID)

Parameter

areaID - ID number for area to clear.

Clears all user data from a given area. Note that this will not touch the room user data.

Example

display(clearAreaUserData(34))
-- I did have data in that area, so it returns:
true

display(clearAreaUserData(34))
-- There is no data NOW, so it returns:
false

Available in Mudlet3.0+

clearAreaUserDataItem

clearAreaUserDataItem(areaID, key)

Removes the specific key and value from the user data from a given area.

Available in Mudlet3.0+

Example

display(getAllAreaUserData(34))
{
  description = [[<area description here>]],
  ruler = "Queen Morgase Trakand"
}

display(clearAreaUserDataItem(34,"ruler"))
true

display(getAllAreaUserData(34))
{
  description = [[<area description here>]],
}

display(clearAreaUserDataItem(34,"ruler"))
false

clearMapSelection

clearMapSelection()

Clears any selected rooms from the map (i.e. they are highlighted in orange).

Returns true if rooms are successfully cleared, false if nothing selected or cleared.

clearMapUserData

clearMapUserData()

Clears all user data stored for the map itself. Note that this will not touch the area or room user data.

Available in Mudlet3.0+

Example

display(clearMapUserData())
-- I did have user data stored for the map, so it returns:
true

display(clearMapUserData())
-- There is no data NOW, so it returns:
false

clearMapUserDataItem

clearMapUserDataItem(mapID, key)

Removes the specific key and value from the user data from the map user data.

Example

display(getAllMapUserData())
{
  description = [[<map description here>]],
  last_modified = "1483228799"
}

display(clearMapUserDataItem("last_modified"))
true

display(getAllMapUserData())
{
  description = [[<map description here>]],
}

display(clearMapUserDataItem("last_modified"))
false

Available in Mudlet3.0+

clearRoomUserData

clearRoomUserData(roomID)

Clears all user data from a given room.

Note: Returns a boolean true if any data was removed from the specified room and false if there was nothing to erase since Mudlet 3.0.

Example

display(clearRoomUserData(3441))
-- I did have data in that room, so it returns:
true

display(clearRoomUserData(3441))
-- There is no data NOW, so it returns:
false

clearRoomUserDataItem

clearRoomUserDataItem(roomID, key)

Removes the specific key and value from the user data from a given room.

Returns a boolean true if data was found against the give key in the user data for the given room and it is removed, will return false if exact key not present in the data. Returns nil if the room for the roomID not found.

Example

display(getAllRoomUserData(3441))
{
  description = [[
From this ledge you can see out across a large cavern to the southwest. The
east side of the cavern is full of stalactites and stalagmites and other
weird rock formations. The west side has a path through it and an exit to the
south. The sound of falling water pervades the cavern seeming to come from
every side. There is a small tunnel to your east and a stalactite within arms
reach to the south. It appears to have grown till it connects with the
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
  doorname_up = "trapdoor"
}

display(clearRoomUserDataItem(3441,"doorname_up"))
true

display(getAllRoomUserData(3441))
{
  description = [[
From this ledge you can see out across a large cavern to the southwest. The
east side of the cavern is full of stalactites and stalagmites and other
weird rock formations. The west side has a path through it and an exit to the
south. The sound of falling water pervades the cavern seeming to come from
every side. There is a small tunnel to your east and a stalactite within arms
reach to the south. It appears to have grown till it connects with the
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
}

display(clearRoomUserDataItem(3441,"doorname_up"))
false

Available in Mudlet3.0+

clearSpecialExits

clearSpecialExits(roomID)

Removes all special exits from a room.

Example

clearSpecialExits(1337)

if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example
  echo("All special exits successfully cleared from 1337.\n")
end

closeMapWidget

closeMapWidget(): closes (hides) the map window (similar to clicking on the map icon)

Available in Mudlet4.7+

connectExitStub

connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])

Connects existing rooms with matching exit stubs. If you only give it a roomID and a direction, it'll work out which room should be linked to it that has an appropriate opposite exit stub and is located in the right direction. You can also just specify from and to room IDs, and it'll smartly use the right direction to link in. Lastly, you can specify all three arguments - fromID, toID and the direction (in that order) if you'd like to be explicit, or use setExit() for the same effect.

Parameters

fromID:

Room ID to set the exit stub in.

direction:

You can either specify the direction to link the room in, and/or a specific room ID (see below). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").

toID:

The room ID to link this room to. If you don't specify it, the mapper will work out which room should be logically linked.

createMapLabel

labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])

Creates a text label on the map at given coordinates, with the given background and foreground colors. It can go above or below the rooms, scale with zoom or stay a static size. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a script can reduce the size of the saved map somewhat. It returns a label ID that you can use later for deleting it.

The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of getRoomCoordinates() will place the label near that room.

Historical Version Note

Note: Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!

Parameters

areaID:

Area ID where to put the label.

text:

The text to put into the label. To get a multiline text label add a '\n' between the lines.

posX, posY, posZ:

Position of the label in (floating point numbers) room coordinates.

fgRed, fgGreen, fgBlue:

Foreground color or text color of the label.

bgRed, bgGreen, bgBlue:

Background color of the label.

zoom:

(optional) Zoom factor of the label if noScaling is false. Higher zoom will give higher resolution of the text and smaller size of the label. Default is 30.0.

fontSize:

(optional, but needed if zoom is provided) Size of the font of the text. Default is 50.

showOnTop:

(optional) If true the label will be drawn on top of the rooms and if it is false the label will be drawn as a background, defaults to true if not given.

noScaling:

(optional) If true the label will have the same size when you zoom in and out in the mapper, If it is false the label will scale when you zoom the mapper, defaults to true if not given.

fontName:

(optional) font name to use.

foregroundTransparency

(optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.

backgroundTransparency

(optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.

temporary

(optional, from Mudlet version 4.17.0) if true does not save the image that the label makes in map save files, defaults to false if not given, or for prior versions of Mudlet.

Example

-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB
-- zoom is only relevant when when you're using a label of a static size, so we use 0
-- and we use a font size of 20 for our label, which is a small medium compared to the map
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)

-- to create a multi line text label we add '\n' between lines
-- the position is placed somewhat to the northeast of the center of the map
-- this label will be scaled as you zoom the map.
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)

local x,y,z = getRoomCoordinates(getPlayerRoom())
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)

createMapImageLabel

labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])

Creates an image label on the map at the given coordinates, with the given dimensions and zoom. You might find the default room and image size correlation to be too big - try reducing the width and height of the image then, while also zooming in the same amount. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a external file available when the map file is loaded, can avoid expanding the size of the saved map considerably.

The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of getRoomCoordinates() will place the label near that room.

Example

-- 138 is our pretend area ID
-- next, inside [[]]'s, is the exact location of our image
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map
-- 482 is the width of the image - we divide it by 100 to scale it down, and then we'll zoom it by 100 - making the image take up about 4 rooms in width then
-- 555 is the original height of the image
-- 100 is how much we zoom it by, 1 would be no zoom
-- false to make it go below our rooms
-- (from 4.17.0) true to not save the label's image in the map file afterwards
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)

createMapper

createMapper([name of userwindow], x, y, width, height)

Creates a miniconsole window for the mapper to render in, the with the given dimensions. You can only create one mapper at a time, and it is not currently possible to have a label on or under the mapper - otherwise, clicks won't register.

Note: name of userwindow available in Mudlet 4.6.1+

Note: If this command is not used then clicking on the Main Toolbar's Map button will create a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the Map button will toggle between showing and hiding the map whether it was created using the createMapper function or as a dock-able widget.

Example

createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display

-- another example:
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})
 
local mapper = Geyser.Mapper:new({
  name = "mapper",
  x = "70%", y = 0, -- edit here if you want to move it
  width = "30%", height = "50%"
}, main)

createRoomID

usableId = createRoomID([minimumStartingRoomId])

Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs.

Parameters

minimumStartingRoomId (optional, available in Mudlet 3.0+):

If provided, specifies a roomID to start searching for an empty one at, instead of 1. Useful if you'd like to ensure certain areas have specific room number ranges, for example. If you you're working with a huge map, provide the last used room ID to this function for an available roomID to be found a lot quicker.

deleteArea

deleteArea(areaID or areaName)

Deletes the given area and all rooms in it. Returns true on success or nil + error message otherwise.

deleteMap

deleteMap()

Deletes the entire map. This may be useful whilst initially setting up a mapper package for a new Game to clear faulty map data generated up to this point.

deleteMapLabel

deleteMapLabel(areaID, labelID)

Deletes a map label from a specific area.

deleteRoom

deleteRoom(roomID)

Deletes an individual room, and unlinks all exits leading to and from it.

Example

deleteRoom(335)

disableMapInfo

disableMapInfo(label)

Disable the particular map info - same as toggling off checkbox from select box under mapper.

Parameters

label:

Name under which map info to be disabled was registered.

Available in Mudlet4.11+

enableMapInfo

enableMapInfo(label)

Enable the particular map info - same as toggling on checkbox from select box under mapper.

Parameters

label:

Name under which map info to be enabled was registered.

Available in Mudlet4.11+

getAllAreaUserData

dataTable = getAllAreaUserData(areaID)

Returns all the user data items stored in the given area ID; will return an empty table if there is no data stored or nil if there is no such area with that ID.

Example

display(getAllAreaUserData(34))
--might result in:--
{
  country = "Andor",
  ruler = "Queen Morgase Trakand"
}

Available in Mudlet3.0+

getAllMapUserData

dataTable = getAllMapUserData()

Returns all the user data items stored at the map level; will return an empty table if there is no data stored.

getAllRoomEntrances

exitsTable = getAllRoomEntrances(roomID)

Returns an indexed list of normal and special exits leading into this room. In case of two-way exits, this'll report exactly the same rooms as getRoomExits(), but this function has the ability to pick up one-way exits coming into the room as well.

Available in Mudlet3.0+

Example

-- print the list of rooms that have exits leading into room 512
for _, roomid in ipairs(getAllRoomEntrances(512)) do 
  print(roomid)
end

getAllRoomUserData

dataTable = getAllRoomUserData(roomID)

Returns all the user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. Can be useful if the user was not the one who put the data in the map in the first place!

See also: getRoomUserDataKeys() - for a related command that only returns the data keys.

Available in Mudlet3.0+

Example

display(getAllRoomUserData(3441))
--might result in:--
{
  description = [[
From this ledge you can see out across a large cavern to the southwest. The
east side of the cavern is full of stalactites and stalagmites and other
weird rock formations. The west side has a path through it and an exit to the
south. The sound of falling water pervades the cavern seeming to come from
every side. There is a small tunnel to your east and a stalactite within arms
reach to the south. It appears to have grown till it connects with the
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
  doorname_up = "trapdoor"
}

getAreaExits

roomTable = getAreaExits(areaID, showExits)

Returns a table (indexed or key-value) of the rooms in the given area that have exits leading out to other areas - that is, border rooms.

See also: setExit(), getRoomExits()

Parameters

areaID:

Area ID to list the exits for.

showExits:

Boolean argument, if true then the exits that lead out to another area will be listed for each room.

Example

-- list all border rooms for area 44:
getAreaExits(44)

-- returns:
--[[
{
  7091,
  10659,
  11112,
  11122,
  11133,
  11400,
  12483,
  24012
}
]]

-- list all border rooms for area 44, and the exits within them that go out to other areas:
getAreaExits(44, true)
--[[
{
  [12483] = {
    north = 27278
  },
  [11122] = {
    ["enter grate"] = 14551
  },
  [11112] = {
    ["enter grate"] = 14829
  },
  [24012] = {
    north = 22413
  },
  [11400] = {
    south = 10577
  },
  [11133] = {
    ["enter grate"] = 15610
  },
  [7091] = {
    down = 4411
  },
  [10659] = {
    ["enter grate"] = 15510
  }
}
]]

getAreaRooms

getAreaRooms(area id)

Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or nil if no such area exists. Indexing starts at 0.

Example

-- using the sample findAreaID() function defined in the getAreaTable() example, 
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID
function echoRoomList(areaname)
  local id, msg = findAreaID(areaname)
  if id then
    local roomlist, endresult = getAreaRooms(id), {}
  
    -- obtain a room list for each of the room IDs we got
    for _, id in pairs(roomlist) do
      endresult[id] = getRoomName(id)
    end
  
    -- now display something half-decent looking
    cecho(string.format(
      "List of all rooms in %s (%d):\n", msg, table.size(endresult)))

    for roomid, roomname in pairs(endresult) do
      cecho(string.format(
        "%6s: %s\n", roomid, roomname))
    end
  elseif not id and msg then
    echo("ID not found; " .. msg)
  else
    echo("No areas matched the query.")
  end
end

getAreaTable

areaTable = getAreaTable()

Returns a key(area name)-value(area id) table with all known areas and their IDs.

Historical Version Note

Note: Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.

See also: getAreaTableSwap()

Example

-- example function that returns the area ID for a given area

function findAreaID(areaname)
  local list = getAreaTable()

  -- iterate over the list of areas, matching them with substring match. 
  -- if we get match a single area, then return it's ID, otherwise return
  -- 'false' and a message that there are than one are matches
  local returnid, fullareaname
  for area, id in pairs(list) do
    if area:find(areaname, 1, true) then
      if returnid then return false, "more than one area matches" end
      returnid = id; fullareaname = area
    end
  end
  
  return returnid, fullareaname
end

-- sample use:
local id, msg = findAreaID("blahblah")
if id then
  echo("Found a matching ID: " .. id)
elseif not id and msg then
  echo("ID not found: " .. msg)
else
  echo("No areas matched the query.")
end

getAreaTableSwap

areaTable = getAreaTableSwap()

Returns a key(area id)-value(area name) table with all known areas and their IDs. Unlike getAreaTable which won't show you all areas with the same name by different IDs, this function will.

Historical Version Note

Note: Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.

getAreaUserData

dataValue = getAreaUserData(areaID, key)

Returns a specific data item stored against the given key for the given area ID number. This is very like the corresponding Room User Data command but intended for per area rather than for per room data (for storage of data relating to the whole map see the corresponding Map User Data commands.)

Returns the user data value (string) stored at a given room with a given key (string), or a Lua nil and an error message if the key is not present in the Area User Data for the given Area ID. Use setAreaUserData() function for storing the user data.

See also: clearAreaUserData(), clearAreaUserDataItem(), getAllAreaUserData(), searchAreaUserData(), setAreaUserData()

Example

display(getAreaUserData(34, "country"))
-- might produce --
"Andor"

getCustomEnvColorTable

envcolors = getCustomEnvColorTable()

Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.

getCustomLines

lineTable = getCustomLines(roomID): See also: addCustomLine(), removeCustomLine()

Returns a table including all the details of the custom exit lines, if any, for the room with the id given.

Parameters

roomID:

Room ID to return the custom line details of.

Available in Mudlet3.0.+

Example

display getCustomLines(1)
{
  ["climb Rope"] = {
    attributes = {
      color = {
        b = 0,
        g = 128,
        r = 128
      },
      style = "dash dot dot line",
      arrow = false
    },
    points = {
      {
        y = 9.5,
        x = 4.5
      },
      {
        y = 9.5,
        x = 6
      },
      [0] = {
        y = 5.5,
        x = 4.5
      }
    }
  },
  N = {
    attributes = {
      color = {
        b = 255,
        g = 255,
        r = 0
      },
      style = "dot line",
      arrow = true
    },
    points = {
      [0] = {
        y = 27,
        x = -3
      }
    }
  }
}

getCustomLines1

lineTable = getCustomLines1(roomID)

This is a replacement for getCustomLines(...) that outputs the tables for the coordinates for the points on the custom line in an order and format that can be fed straight back into an addCustomLine(...) call; similarly the color parameters are also reported in the correct format to also be reused in the same manner. This function is intended to make it simpler for scripts to manipulate such lines.

Available in Mudlet 4.16+

Parameters

roomID:

Room ID to return the custom line details of.

Returns: a table including all the details of the custom exit lines, if any, for the room with the id given.

Example

display getCustomLines1(1)
{
  ["climb Rope"] = {
    attributes = {
      color = { 128, 128, 0 },
      style = "dash dot dot line",
      arrow = false
    },
    points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } } 
  },
  N = {
    attributes = {
      color = { 0, 255, 255 },
      style = "dot line",
      arrow = true
    },
    points = { { -3, 27, 3 } }
  }
}

getDoors

doors = getDoors(roomID)

Returns a key-value table with the cardinal direction as the key and the door value as a number. If there are no doors in a room, it returns an empty table.

Parameters

roomID:

Room ID to check for doors in.

getExitStubs

stubs = getExitStubs(roomid)

Returns an indexed table (starting at 0) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. Returns nil plus error message of called on a non-existent room.

The directions numbers can be deciphered using this table;

  local stubmap = {
      [1] = "north",  [2] = "northeast",  [3] = "northwest",  [4] = "east",
      [5] = "west",   [6] = "south",      [7] = "southeast",  [8] = "southwest",
      [9] = "up",     [10] = "down",      [11] = "in",        [12] = "out",
      [13] = "northup", [14] = "southdown", [15] = "southup", [16] = "northdown",
      [17] = "eastup", [18] = "westdown", [19] = "westup",    [20] = "eastdown"
  }

Example

-- show the exit stubs in room 6 as numbers
local stubs = getExitStubs(6)
for i = 0, #stubs do print(stubs[i]) end

Historical Version Note

Note: Previously would throw a lua error on non-existent room - now returns nil plus error message (as does other run-time errors) - previously would return just a nil on NO exit stubs but now returns a notification error message as well, to aide disambiguation of the nil value.

getExitStubs1

stubs = getExitStubs1(roomid)

Returns an indexed table (starting at 1) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. As this function starts indexing from 1 as it is default in Lua, you can use ipairs() to iterate over the results.

See also: getExitStubs()

Example

-- show the exit stubs in room 6 as numbers
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end

getExitWeights

weights = getExitWeights(roomid)

Returns a key-value table of the exit weights that a room has, with the direction or special exit as a key and the value as the exit weight. If a weight for a direction wasn't yet set, it won't be listed.

Parameters

roomid:

Room ID to view the exit weights in.

getGridMode

TrueOrFalse = getGridMode(areaID)

Use this to see, if a specific area has grid/wilderness view mode set. This way, you can also calculate from a script, how many grid areas a map has got in total.

Available in Mudlet3.11+

Parameters

areaID:

Area ID (number) to view the grid mode of.

getMapEvents

mapevents = getMapEvents()

Returns a list of map events currently registered. Each event is a dictionary with the keys uniquename, parent, event name, display name, and arguments, which correspond to the arguments of addMapEvent().

Example

addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite

addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")

local mapEvents = getMapEvents()
for _, event in ipairs(mapEvents) do
  echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))
end

Available in Mudlet3.3+

getMapLabel

labelinfo = getMapLabel(areaID, labelID or labelText)

Returns a key-value table describing that particular label in an area. Keys it contains are the X, Y, Z coordinates, Height and Width, BgColor, FgColor, Pixmap, and the Text it contains. If the label is an image label, then Text will be set to the no text string.

BgColor and FgColor are tables with r,g,b keys, each holding 0-255 color component value.

Pixmap is base64 encoded image of label.

Note: BgColor, FgColor, Pixmap are available in Mudlet 4.11+

Parameters

areaID: areaID from which to retrieve label
labelID: labelID (getMapLabels return table key) or labelText (exact match)

Example

lua getMapLabels(52)
{
  "no text",
  [0] = "test"
}

lua getMapLabel(52, 0)
{
  Y = -2,
  X = -8,
  Z = 11,
  Height = 3.9669418334961,
  Text = "test",
  Width = 8.6776866912842,
  BgColor = {
    b = 0,
    g = 0,
    r = 0
  },
  FgColor = {
    b = 50,
    g = 255,
    r = 255
  },
  Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)
}

lua getMapLabel(52, "no text")
{
  Y = 8,
  X = -15,
  Z = 11,
  Height = 7.2520666122437,
  Text = "no text"
  Width = 11.21900844574,
  BgColor = {
    b = 0,
    g = 0,
    r = 0
  },
  FgColor = {
    b = 50,
    g = 255,
    r = 255
  },
  Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)
}

getMapLabels

arealabels = getMapLabels(areaID)

Returns an indexed table (that starts indexing from 0) of all of the labels in the area, plus their label text. You can use the label id to deleteMapLabel() it.

If there are no labels in the area at all, it will return an empty table.

Example

display(getMapLabels(43))
table {
  0: ''
  1: 'Waterways'
}

deleteMapLabel(43, 0)
display(getMapLabels(43))
table {
  1: 'Waterways'
}

getMapMenus

getMapMenus()

Returns a table with the available map menus as key-value in the format of map menu - parent item. If an item is positioned at the menu's top-level, the value will say top-level.

If you haven't opened a map yet, getMapMenus() will return nil+error message. If you don't have any map labels yet, an empty table {} is returned.

getMapSelection

getMapSelection()

Returns a table containing details of the current mouse selection in the 2D mapper.

Reports on one or more rooms being selected (i.e. they are highlighted in orange).

The contents of the table will vary depending on what is currently selected. If the selection is of map rooms then there will be keys of center and rooms: the former will indicates the center room (the one with the yellow cross-hairs) if there is more than one room selected or the only room if there is only one selected (there will not be cross-hairs in that case); the latter will contain a list of the one or more rooms.

Example - several rooms selected

display(getMapSelection())
{
  center = 5013,
  rooms = {
    5011,
    5012,
    5013,
    5014,
    5018,
    5019,
    5020
  }
}

Example - one room selected

display(getMapSelection())
{
  center = 5013,
  rooms = {
    5013
  }
}

Example - no or something other than a room selected

display(getMapSelection())
{
}

Available in Mudlet3.17+

getMapUserData

getMapUserData( key )

Parameters

key:

string used as a key to select the data stored in the map as a whole.

Returns the user data item (string); will return a nil+error message if there is no data with such a key in the map data.

Example

display(getMapUserData("last updated"))
--might result in:--
"December 5, 2020"

Available in Mudlet3.0+

getMapZoom

getMapZoom([areaID])

Gets the current 2D map zoom level. Added in Mudlet 4.17.0 also with the option to get the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet remembering the zoom level last used for each area and with the revision of the setMapZoom() function to also take an areaID to work on instead of the current area being viewed in the map.

getPath

getPath(roomID from, roomID to)

Returns a boolean true/false if a path between two room IDs is possible. If it is, the global speedWalkDir table is set to all of the directions that have to be taken to get there, and the global speedWalkPath table is set to all of the roomIDs you'll encounter on the way, and as of 3.0, speedWalkWeight will return all of the room weights. Additionally returns the total cost (all weights added up) of the path after the boolean argument in 3.0.

getPlayerRoom

getPlayerRoom()

Returns the current player location as set by centerview().

getRoomArea

getRoomArea(roomID)

Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by getAreaTable() function, or use the getRoomAreaName() function.

Note: If the room ID does not exist, this function will raise an error.

Example

display("Area ID of room #100 is: "..getRoomArea(100))

display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))

getRoomAreaName

getRoomAreaName(areaID or areaName)

Returns the area name for a given area id; or the area id for a given area name.

Note: Despite the name, this function will not return the area name for a given room id (or room name) directly. However, renaming or revising it would break existing scripts.

Example

echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))

getRoomChar

getRoomChar(roomID)

Returns the single ASCII character that forms the symbol for the given room id.

Since Mudlet version 3.8 : this facility has been extended:

Returns the string (UTF-8) that forms the symbol for the given room id; this may have been set with either setRoomChar() or with the symbol (was letter in prior versions) context menu item for rooms in the 2D Map.

getRoomCharColor

r,g,b = getRoomCharColor(roomID)

Returns the color of the Room Character as a set of r,g,b color coordinates.

See also: setRoomCharColor(), getRoomChar()

Parameters

roomID:

The room ID to get the room character color from

Returns

The color as 3 separate numbers, red, green, and blue from 0-255

Example

-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0
local r,g,b = getRoomCharColor(12345)
decho(f"Room Character for room 12345 is <{r},{g},{b}>this color.<r> It is made up of <{r},0,0>{r} red<r>, <0,{g},0>{g} green<r>, <0,0,{b}> {b} blue<r>.\")

getRoomCoordinates

x,y,z = getRoomCoordinates(roomID)

Returns the room coordinates of the given room ID.

See also: setRoomCoordinates()

Example

local x,y,z = getRoomCoordinates(roomID)
echo("Room Coordinates for "..roomID..":")
echo("\n     X:"..x)
echo("\n     Y:"..y)
echo("\n     Z:"..z)

-- A quick function that will find all rooms on the same z-position in an area; this is useful if, say, you want to know what all the same rooms on the same "level" of an area is.
function sortByZ(areaID, zval)
  local area = getAreaRooms(areaID)
  local t = {}
  for _, id in ipairs(area) do
    local _, _, z = getRoomCoordinates(id)
    if z == zval then
      table.insert(t, id)
    end
  end
  return t
end

getRoomEnv

envID = getRoomEnv(roomID)

Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.

Example

function checkID(id)
  echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))
end

getRoomExits

getRoomExits (roomID): Returns the currently known non-special exits for a room in an key-index form: exit = exitroomid.

getRoomHashByID

getRoomHashByID(roomID)

Returns a room hash that is associated with a given room ID in the mapper. This is primarily for games that make use of hashes instead of room IDs. It may be used to share map data while not sharing map itself. nil is returned if no room is not found.

getRoomIDbyHash

roomID = getRoomIDbyHash(hash)

Returns a room ID that is associated with a given hash in the mapper. This is primarily for games that make use of hashes instead of room IDs (like Avalon.de). -1 is returned if no room ID matches the hash.

getRoomName

getRoomName(roomID)

Returns the room name for a given room id.

Example

echo(string.format("The name of the room id #455 is %s.", getRoomName(455))

getRooms

rooms = getRooms()

Returns the list of all rooms in the map in the whole map in roomid - room name format.

Example

-- simple, raw viewer for rooms in the world
display(getRooms())

-- iterate over all rooms in code
for id,name in pairs(getRooms()) do
  print(id, name)
end

getRoomsByPosition

roomTable = getRoomsByPosition(areaID, x,y,z)

Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.

Note: The returned table starts indexing from 0 and not the usual lua index of 1, which means that using # to count the size of the returned table will produce erroneous results - use table.size() instead.

Example

-- sample alias to determine a room nearby, given a relative direction from the current room

local otherroom
if matches[2] == "" then
  local w = matches[3]
  local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)
  local has = table.contains
  if has({"west", "left", "w", "l"}, w) then
    x = (x or ox) - 1; y = (y or oy); z = (z or oz)
  elseif has({"east", "right", "e", "r"}, w) then
    x = (x or ox) + 1; y = (y or oy); z = (z or oz)
  elseif has({"north", "top", "n", "t"}, w) then
    x = (x or ox); y = (y or oy) + 1; z = (z or oz)
  elseif has({"south", "bottom", "s", "b"}, w) then
    x = (x or ox); y = (y or oy) - 1; z = (z or oz)
  elseif has({"northwest", "topleft", "nw", "tl"}, w) then
    x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)
  elseif has({"northeast", "topright", "ne", "tr"}, w) then
    x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)
  elseif has({"southeast", "bottomright", "se", "br"}, w) then
    x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)
  elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then
    x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)
  elseif has({"up", "u"}, w) then
    x = (x or ox); y = (y or oy); z = (z or oz) + 1
  elseif has({"down", "d"}, w) then
    x = (x or ox); y = (y or oy); z = (z or oz) - 1
  end

  local carea = getRoomArea(mmp.currentroom)
  if not carea then mmp.echo("Don't know what area are we in.") return end

  otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))

  if not otherroom then
    mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return
  else
    mmp.echo("The room "..w.." of us has an ID of "..otherroom)
  end

getRoomUserData

getRoomUserData(roomID, key)

Returns the user data value (string) stored at a given room with a given key (string), or "" if none is stored. Use setRoomUserData() function for setting the user data.

Example

display(getRoomUserData(341, "visitcount"))

getRoomUserData(roomID, key, enableFullErrorReporting)

Returns the user data value (string) stored at a given room with a given key (string), or, if the boolean value enableFullErrorReporting is true, nil and an error message if the key is not present or the room does not exist; if enableFullErrorReporting is false an empty string is returned but then it is not possible to tell if that particular value is actually stored or not against the given key.

Example

local vNum = 341
result, errMsg = getRoomUserData(vNum, "visitcount", true)
if result ~= nil then
    display(result)
else
    echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")
end

getRoomUserDataKeys

getRoomUserDataKeys(roomID)

Returns all the keys for user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. Can be useful if the user was not the one who put the data in the map in the first place!

Example

display(getRoomUserDataKeys(3441))
--might result in:--
{
  "description",
  "doorname_up",
}

Available in Mudlet3.0+

getRoomWeight

getRoomWeight(roomID)

Returns the weight of a room. By default, all new rooms have a weight of 1.

getSpecialExits

exits = getSpecialExits(roomID[, listAllExits])

Parameters

roomID:

Room ID to return the special exits of.

listAllExits:

In the case where there is more than one special exit to the same room ID list all of them.

Returns a roomid table of sub-tables containing name/command and exit lock status, of the special exits in the room. If there are no special exits in the room, the table returned will be empty

Historical Version Note

(Since TBA) In the case where there is more than one special exit to the same room ID list all of them.

Before TBA (likely to be Mudlet version 4.11.0), if more than one special exit goes to the same exit room id then one of those exits is returned at random. Since TBA this will be the best (i.e. lowest-weight) exit that is not locked; should none be unlocked then the lowest locked one will be listed. In case of a tie, one of the tying exits will be picked at random.

getSpecialExitsSwap

getSpecialExitsSwap(roomID)

Very similar to getSpecialExits() function, but returns the rooms in the command - roomid style.

gotoRoom

gotoRoom (roomID): Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".

In case this isn't working, and you are coding your own mapping script, see here how to implement additional functionality necessary.

hasExitLock

status = hasExitLock(roomID, direction)

Returns true or false depending on whenever a given exit leading out from a room is locked. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").

Example

-- check if the east exit of room 1201 is locked
display(hasExitLock(1201, 4))
display(hasExitLock(1201, "e"))
display(hasExitLock(1201, "east"))

hasSpecialExitLock

hasSpecialExitLock(from roomID, to roomID, moveCommand)

Returns true or false depending on whenever a given exit leading out from a room is locked. moveCommand is the action to take to get through the gate.

highlightRoom

highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)

Highlights a room with the given color, which will override its environment color. If you use two different colors, then there'll be a shading from the center going outwards that changes into the other color.

Parameters

roomID

ID of the room to be colored.

color1Red, color1Green, color1Blue

RGB values of the first color.

color2Red, color2Green, color2Blue

RGB values of the second color.

highlightRadius

The radius for the highlight circle - if you don't want rooms beside each other to overlap, use 1 as the radius.

color1Alpha and color2Alpha

Transparency values from 0 (completely transparent) to 255 (not transparent at all).

killMapInfo

killMapInfo(label)

Delete a map info contributor entirely - it will be not available anymore.

Parameters

label:

Name under which map info to be removed was registered.

Available in Mudlet4.11+

loadJsonMap

loadJsonMap(pathFileName)

Parameters

pathFileName a string that is an absolute path and file name to read the data from.

Load the Mudlet map in text (JSON) format. It does take longer than loading usual map file (.dat in binary) so it will show a progress dialog.

loadMap

loadMap(file location)

Loads the map file from a given location. The map file must be in Mudlet's format - saved with saveMap() or, as of the Mudlet 3.0 may be a MMP XML map conforming to the structure used by I.R.E. for their downloadable maps for their MUD games.

Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.

Using no arguments will load the last saved map.

  loadMap("/home/user/Desktop/Mudlet Map.dat")

Note: A file name ending with .xml will indicate the XML format.

lockExit

lockExit(roomID, direction, lockIfTrue)

Locks a given exit from a room. The destination may remain accessible through other paths, unlike lockRoom. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").

lockRoom

lockRoom (roomID, lockIfTrue)

Locks a given room id from future speed walks (thus the mapper will never path through that room).

lockSpecialExit

lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)

Locks a given special exit, leading from one specific room to another that uses a certain command from future speed walks (thus the mapper will never path through that special exit).

Example

lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit

moveMapWidget

moveMapWidget(Xpos, Ypos): moves the map window to the given position.; See also: openMapWidget(), closeMapWidget(), resizeMapWidget()

Parameters

Xpos:

X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.

Ypos:

Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.

Available in Mudlet4.7+

openMapWidget

openMapWidget([dockingArea | Xpos, Ypos, width, height])

means either of these are fine:

openMapWidget()
openMapWidget(dockingArea)
openMapWidget(Xpos, Ypos, width, height)

opens a map window with given options.

Available in Mudlet4.7+

Parameters

Note: If no parameter is given the map window will be opened with the saved layout or at the right docking position (similar to clicking the icon)

dockingArea:

If only one parameter is given this parameter will be a string that contains one of the possible docking areas the map window will be created in (f" floating "t" top "b" bottom "r" right and "l" left)

Note: If 4 parameters are given the map window will be created in floating state

Xpos:

X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.

Ypos:

Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.

width:

The width map window, in pixels. Passed as an integer number.

height:

The height map window, in pixels. Passed as an integer number.

pauseSpeedwalk

pauseSpeedwalk()

Pauses a speedwalk started using speedwalk()

Available in Mudlet4.13+

local ok, err = pauseSpeedwalk()
if not ok then
  debugc(f"Error: unable to pause speedwalk because {err}\n")
  return
end

registerMapInfo

registerMapInfo(label, function)

Adds an extra 'map info' to the mapper widget which can be used to display custom information.

Available in Mudlet4.11+

Note: You can register multiple map infos - just give them unique names and toggle whichever ones you need.

Parameters

label:

Name under which map info will be registered and visible in select box under mapper. You can use it later to kill map info, enable it, disable it or overwrite using registerMapInfo() again.

function:

Callback function that will be responsible for returning information how to draw map info fragment.

Callback function is called with following arguments:

roomId - current roomId or currently selected room (when multiple selection is made this is center room)
selectionSize - how many rooms are selected
areaId - roomId's areaId
displayedAreaId - areaId that is currently displayed

Callback needs to return following:

text - text that will be displayed (when empty, nothing will be displayed, if you want to "reserve" line or lines use not empty value " " or add line breaks "\n")
isBold (optional) - true/false - determines whether text will be bold
isItalic (optional) - true/false - determines whether text will be italic
color r (optional) - color of text red component (0-255)
color g (optional) - color of text green component (0-255)
color b (optional) - color of text blue component (0-255)

Note: Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.

registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea) 
  return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),
  true, true, 0, 255, 0
end)
enableMapInfo("My very own handler!")

Example will display something like that:

Using function arguments is completely optional and you can determine whether and how to display map info completely externally.

registerMapInfo("Alert", function() 
  if character.hp < 20 then
    return "Look out! Your HP is getting low", true, false, unpack(color_table.red) -- will display red, bolded warning whne character.hp is below 20
  else
    return "" -- will not return anything
  end
end)
enableMapInfo("Alert")

resumeSpeedwalk

resumeSpeedwalk()

Continues a speedwalk paused using pauseSpeedwalk()

Available in Mudlet4.13+

local ok, err = resumeSpeedwalk()
if not ok then
  cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")
  return
end
cecho("\n<green>Successfully resumed speedwalk!\n")

removeCustomLine

removeCustomLine(roomID, direction)

Removes the custom exit line that's associated with a specific exit of a room.

Example

-- remove custom exit line that starts in room 315 going north
removeCustomLine(315, "n")

removeMapEvent

removeMapEvent(event name)

Removes the given menu entry from a mappers right-click menu. You can add custom ones with addMapEvent().

Example

addMapEvent("room a", "onFavorite") -- add one to the general menu
removeMapEvent("room a") -- removes the said menu

removeMapMenu

removeMapMenu(menu name)

Removes the given submenu from a mappers right-click menu. You can add custom ones with addMapMenu().

Example

addMapMenu("Test") -- add submenu to the general menu
removeMapMenu("Test") -- removes that same menu again

removeSpecialExit

removeSpecialExit(roomID, command)

Removes the special exit which is accessed by command from the room with the given roomID.

Example

addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2
removeSpecialExit(1, "pull rope") -- removes the exit again

resetRoomArea

resetRoomArea (roomID)

Unassigns the room from its given area. While not assigned, its area ID will be -1. Note that since Mudlet 3.0 the "default area" which has the id of -1 may be selectable in the area selection widget on the mapper - although there is also an option to conceal this in the settings.

resizeMapWidget

resizeMapWidget(width, height): resizes a map window with given width, height.; See also: openMapWidget(), closeMapWidget(), moveMapWidget()

Available in Mudlet4.7+

Parameters

width:

The width of the map window, in pixels. Passed as an integer number.

height:

The height of the map window, in pixels. Passed as an integer number.

roomExists

roomExists(roomID)

Returns a boolean true/false depending if the room with that ID exists (is created) or not.

roomLocked

locked = roomLocked(roomID)

Returns true or false whenever a given room is locked.

saveJsonMap

saveJsonMap([pathFileName])

Saves all the data that is normally held in the Mudlet map (.dat as a binary format) in text (JSON) format. It does take longer to do this, so a progress dialog will be shown indicating the status.

saveMap

saveMap([location], [version])

Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work. You can also save the map in the Mapper settings tab.

Parameters

location

(optional) save the map to the given location if provided, or the default one otherwise.

version

(optional) map version as a number to use when saving (Mudlet 3.17+)

searchAreaUserData

searchAreaUserData(area number | area name[, case-sensitive [, exact-match]]): Searches Areas' User Data in a manner exactly the same as searchRoomUserData() does in all Rooms' User Data, refer to that command for the specific details except to replace references to rooms and room ID numbers there with areas and areas ID numbers.

searchRoom

searchRoom (room number | room name[, case-sensitive [, exact-match]]): Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of roomid = roomname, the optional second and third boolean parameters have been available since Mudlet 3.0;

If no rooms are found, then an empty table is returned.

If you pass it a number instead of a string as just one argument, it'll act like getRoomName() and return the room name.

Examples

-- show the behavior when given a room number:
display(searchRoom(3088))
"The North Road South of Taren Ferry"

-- show the behavior when given a string:
-- shows all rooms containing the text in any case:
display(searchRoom("North road"))
{
   [3114] = "Bend in North road",
   [3115] = "North road",
   [3116] = "North Road",
   [3117] = "North road",
   [3146] = "Bend in the North Road",
   [3088] = "The North Road South of Taren Ferry",
   [6229] = "Grassy Field By North Road"
}
-- or:
--   display(searchRoom("North road",false))
--   display(searchRoom("North road",false,false))
-- would both also produce those results.

-- shows all rooms containing the text in ONLY the letter-case provided:
display(searchRoom("North road",true,false))
{
   [3114] = "Bend in North road",
   [3115] = "North road",
   [3117] = "North road",
}

-- shows all rooms containing ONLY that text in either letter-case:
lua searchRoom("North road",false,true)
{
  [3115] = "North road",
  [3116] = "North Road",
  [3117] = "North road"
}

-- shows all rooms containing only and exactly the given text:
lua searchRoom("North road",true,true)
{
  [3115] = "North road",
  [3117] = "North road"
}

Note: Technically, with both options (case-sensitive and exact-match) set to true, one could just return a list of numbers as we know precisely what the string will be, but it was kept the same for maximum flexibility in user scripts.

searchRoomUserData

searchRoomUserData([key, [value]]): A command with three variants that search though all the rooms in sequence (so not as fast as a user built/maintained index system) and find/reports on the room user data stored:

searchRoomUserData(key, value)

Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key".

searchRoomUserData(key)

Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key".

searchRoomUserData()

Reports a (sorted) list of the unique keys from all rooms with user data with any (case sensitive) "key", available since Mudlet 3.0. It is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.

Available in Mudlet3.0+

Examples

-- if I had stored the details of "named doors" as part of the room user data --
display(searchRoomUserData("doorname_up"))

--[[ could result in a list:
{
  "Eastgate",
  "Northgate",
  "boulderdoor",
  "chamberdoor",
  "dirt",
  "floorboards",
  "floortrap",
  "grate",
  "irongrate",
  "rockwall",
  "tomb",
  "trap",
  "trapdoor"
}]]

-- then taking one of these keys --
display(searchRoomUserData("doorname_up","trapdoor"))

--[[ might result in a list:
{
  3441,
  6113,
  6115,
  8890
}
]]

setAreaName

setAreaName(areaID or areaName, newName)

Names, or renames an existing area to the new name. The area must be created first with addAreaName() and it must be unique.

Note: parameter areaName is available since Mudlet 3.0.

setAreaUserData

setAreaUserData(areaID, key (as a string), value (as a string))

Stores information about an area under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. Returns a lua true value on success. You can have as many keys as you'd like, however a blank key will not be accepted and will produce a lua nil and an error message instead.

Returns true if successfully set.

Available in Mudlet3.0+

Example

-- can use it to store extra area details...
setAreaUserData(34, "country", "Andor.")

-- or a sound file to play in the background (with a script that checks a room's area when entered)...
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")

-- can even store tables in it, using the built-in yajl.to_string function
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)

setCustomEnvColor

setCustomEnvColor(environmentID, r,g,b,a)

Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.

Note: Numbers 1-16 and 257-272 are reserved by Mudlet. 257-272 are the default colors the user can adjust in mapper settings, so feel free to use them if you'd like - but don't overwrite them with this function.

Default colour table for Mudlet mapper.

Example

setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200
local r,g,b = unpack(color_table.blue)
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue

setDoor

setDoor(roomID, exitCommand, doorStatus)

Creates or deletes a door in a room. Doors are purely visual - they don't affect default pathfinding (use a custom script to overcome this). You can use the information to adjust your speedwalking path based on the door information in a room, though.

Doors CAN be set on stub exits - so that map makers can note if there is an obvious door to somewhere even if they do not (yet) know where it goes, perhaps because they do not yet have the key to open it!

Returns true if the change could be made, false if the input was valid but ineffective (door status was not changed), and nil with a message string on invalid input (value type errors).

setExit

setExit(from roomID, to roomID, direction)

Creates a one-way exit from one room to another using a standard direction - which can be either one of n, ne, nw, e, w, s, se, sw, u, d, in, out, the long version of a direction, or a number which represents a direction. If there was an exit stub in that direction already, then it will be automatically deleted for you.

Returns false if the exit creation didn't work.

setExitStub

setExitStub(roomID, direction, set/unset)

Creates or removes an exit stub from a room in a given directions. You can use exit stubs later on to connect rooms that you're sure of are together. Exit stubs are also shown visually on the map, so the mapper can easily tell which rooms need finishing.

Parameters

roomID:

The room to place an exit stub in, as a number.

direction:

The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.

set/unset:

A boolean to create or delete the exit stub.

Example

Create an exit stub to the south from room 8:

setExitStub(8, "s", true)

How to delete all exit stubs in a room:

for i,v in pairs(getExitStubs(roomID)) do
  setExitStub(roomID, v,false)
end

setExitWeight

setExitWeight(roomID, exitCommand, weight)

Gives an exit a weight, which makes it less likely to be chosen for pathfinding. All exits have a weight of 0 by default, which you can increase. Exit weights are set one-way on an exit - if you'd like the weight to be applied both ways, set it from the reverse room and direction as well.

Parameters

roomID:

Room ID to to set the weight in.

exitCommand:

The direction for the exit is in - it can be one of the following: n, ne, e, se, s, sw, w, nw, up, down, in, out, or, if it's a special exit, the special exit command - note that the strings for normal exits are case-sensitive and must currently be exactly as given here.

weight:

Exit weight - by default, all exits have a weight of 0 meaning that the weight of the destination room is use when the route finding code is considering whether to use that exit; setting a value for an exit can increase or decrease the chance of that exit/destination room being used for a route by the route-finding code. For example, if the destination room has very high weight compared to it's neighbors but the exit has a low value then that exit and thus the room is more likely to be used than if the exit was not weighted.

setGridMode

setGridMode(areaID, true/false)

Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode; for the 2D map the custom exit lines will also not be shown if this mode is enabled.

Returns true if the area exists, otherwise false.

regular mode

grid mode

setMapUserData

setMapUserData(key (as a string), value (as a string))

Stores information about the map under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like.

Returns true if successfully set.

Example

-- store general meta information about the map...
setMapUserData("game_name", "Achaea Mudlet map")

-- or who the author was
setMapUserData("author", "Bob")

-- can even store tables in it, using the built-in yajl.to_string function
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))
display("Available game info in the map: ")
display(yajl.to_value(getMapUserData("some table")))

setMapZoom

setMapZoom(zoom[, areaID])

Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in Mudlet 4.17.0 to allow the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet permanently remembering (it is saved within the map file) the zoom level last used for each area and with the addition of the getMapZoom() function.

setRoomArea

setRoomArea(roomID, newAreaID or newAreaName)

Assigns the given room to a new or different area. If the area is displayed in the mapper this will have the room be visually moved into the area as well.

setRoomChar

setRoomChar(roomID, character)

Originally designed for an area in grid mode, takes a single ASCII character and draws it on the rectangular background of the room in the 2D map.

Game-related symbols for your map

toddfast's font - 3000+ scalable vector RPG icons from game-icons.net, as well as a script to download the latest icons and generate a new font.

Example

setRoomChar(431, "#")

setRoomChar(123, "$")

-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings
setRoomChar(666, "👿")

-- clear a symbol with a space
setRoomChar(123, " ")

Historical version information

Since Mudlet version 3.8 this feature has been extended:

This function will now take a short string of any printable characters as a room symbol, and they will be shrunk to fit them all in horizontally but if they become too small that symbol may not be shown if the zoom is such that the room symbol is too small to be legible.
As "_" is now a valid character an existing symbol may be erased with either a space " " or an empty string "" although neither may be effective in some previous versions of Mudlet.
Should the rooms be set to be drawn as circles this is now accommodated and the symbol will be resized to fit the reduce drawing area this will cause.
The range of characters that are available are now dependent on the fonts present in the system and a setting on the "Mapper" tab in the preferences that control whether a specific font is to be used for all symbols (which is best if a font is included as part of a game server package, but has the issue that it may not be displayable if the user does not have that font or chooses a different one) or any font in the user's system may be used (which is the default, but may not display the glyph {the particular representation of a grapheme in a particular font} that the original map creator expected). Should it not be possible to display the wanted symbol in the map because one or more of the required glyphs are not available in either the specified or any font depending on the setting then the replacement character (Unicode code-point U+FFFD '�') will be shown instead. To allow such missing symbols to be handled the "Mapper" tab on the preferences dialogue has an option to display:

an indicator to show whether the symbol can be made just from the selected font (green tick), from the fonts available in the system (yellow warning triangle) or not at all (red cross)
all the symbols used on the map and how they will be displayed both only using the selected font and all fonts
the sequence of code-points used to create the symbol which will be useful when used in conjunction with character selection utilities such as charmap.exe on Windows and gucharmap on unix-like system
a count of the rooms using the particular symbol
a list, limited in entries of the first rooms using that symbol

The font that is chosen to be used as the primary (or only) one for the room symbols is stored in the Mudlet map data so that setting will be included if a binary map is shared to other Mudlet users or profiles on the same system.

setRoomCharColor

setRoomCharColor(roomId, r, g, b)

Parameters

roomID:

Room ID to to set char color to.

r:

Red component of room char color (0-255)

g:

Green component of room char color (0-255)

b:

Blue component of room char color (0-255)

Sets color for room symbol.

setRoomCharColor(2402, 255, 0, 0)
setRoomCharColor(2403, 0, 255, 0)
setRoomCharColor(2404, 0, 0, 255)

Available in Mudlet4.11+

setRoomCoordinates

setRoomCoordinates(roomID, x, y, z)

Sets the given room ID to be at the following coordinates visually on the map, where z is the up/down level. These coordinates are define the location of the room within a particular area (so not globally on the overall map).

Note: 0,0,0 is the center of the map.

Examples

-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$
-- this sets the current room to the supplied coordinates
setRoomCoordinates(roomID,x,y,z)
centerview(roomID)

You can make them relative asa well:

-- alias pattern: ^src (\w+)$

local x,y,z = getRoomCoordinates(previousRoomID)
local dir = matches[2]

if dir == "n" then
  y = y+1
elseif dir == "ne" then
  y = y+1
  x = x+1
elseif dir == "e" then
  x = x+1
elseif dir == "se" then
  y = y-1
  x = x+1
elseif dir == "s" then
  y = y-1
elseif dir == "sw" then
  y = y-1
  x = x-1
elseif dir == "w" then
  x = x-1
elseif dir == "nw" then
  y = y+1
  x = x-1
elseif dir == "u" or dir == "up" then
  z = z+1
elseif dir == "down" then
  z = z-1
end
setRoomCoordinates(roomID,x,y,z)
centerview(roomID)

setRoomEnv

setRoomEnv(roomID, newEnvID)

Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.

setRoomIDbyHash

setRoomIDbyHash(roomID, hash)

Sets the hash to be associated with the given roomID. See also getRoomIDbyHash().

If the room was associated with a different hash, or vice versa, that association will be superseded.

setRoomName

setRoomName(roomID, newName)

Renames an existing room to a new name.

Example

setRoomName(534, "That evil room I shouldn't visit again.")
lockRoom(534, true) -- and lock it just to be safe

setRoomUserData

setRoomUserData(roomID, key (as a string), value (as a string))

Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like.

Returns true if successfully set.

Example

-- can use it to store room descriptions...
setRoomUserData(341, "description", "This is a plain-looking room.")

-- or whenever it's outdoors or not...
setRoomUserData(341, "outdoors", "true")

-- how how many times we visited that room
local visited = getRoomUserData(341, "visitcount")
visited = (tonumber(visited) or 0) + 1
setRoomUserData(341, "visitcount", tostring(visited))

-- can even store tables in it, using the built-in yajl.to_string function
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)

setRoomWeight

setRoomWeight(roomID, weight)

Sets a weight to the given roomID. By default, all rooms have a weight of 1 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.

Note: The minimum allowed room weight is 1.

To completely avoid a room, make use of lockRoom().

speedwalk

speedwalk(dirString, backwards, delay, show)

A speedwalking function will work on cardinal+ordinal directions (n, ne, e, etc.) as well as u (for up), d (for down), in and out. It can be called to execute all directions directly after each other, without delay, or with a custom delay, depending on how fast your game allows you to walk. It can also be called with a switch to make the function reverse the whole path and lead you backwards.

Call the function by doing: speedwalk("YourDirectionsString", true/false, delaytime, true/false)

The delaytime parameter will set a delay between each move (set it to 0.5 if you want the script to move every half second, for instance). It is optional: If you don't indicate it, the script will send all direction commands right after each other. (If you want to indicate a delay, you -have- to explicitly indicate true or false for the reverse flag.)

The show parameter will determine if the commands sent by this function are shown or hidden. It is optional: If you don't give a value, the script will show all commands sent. (If you want to use this option, you -have- to explicitly indicate true or false for the reverse flag, as well as either some number for the delay or nil if you do not want a delay.)

The "YourDirectionsString" contains your list of directions and steps (e.g.: "2n, 3w, u, 5ne"). Numbers indicate the number of steps you want it to walk in the direction specified after it. The directions must be separated by anything other than a letter that can appear in a direction itself. (I.e. you can separate with a comma, spaces, the letter x, etc. and any such combinations, but you cannot separate by the letter "e", or write two directions right next to each other with nothing in-between, such as "wn". If you write a number before every direction, you don't need any further separator. E.g. it's perfectly acceptable to write "3w1ne2e".) The function is not case-sensitive.

If your game only has cardinal directions (n,e,s,w and possibly u,d) and you wish to be able to write directions right next to each other like "enu2s3wdu", you'll have to change the pattern slightly. Likewise, if your game has any other directions than n, ne, e, se, s, sw, w, nw, u, d, in, out, the function must be adapted to that.

Example

speedwalk("16d1se1u")
-- Will walk 16 times down, once southeast, once up. All in immediate succession.

speedwalk("2ne,3e,2n,e")
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.

speedwalk("IN N 3W 2U W", false, 0.5)
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.

speedwalk("5sw - 3s - 2n - w", true)
-- Will walk backwards: east, twice south, thrice north, five times northeast. All in immediate succession.

speedwalk("3w, 2ne, w, u", true, 1.25)
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.

Note: The probably most logical usage of this would be to put it in an alias. For example, have the pattern ^/(.+)$ execute: speedwalk(matches[2], false, 0.7) And have ^//(.+)$ execute: speedwalk(matches[2], true, 0.7) Or make aliases like: ^banktohome$ to execute speedwalk("2ne,e,ne,e,3u,in", true, 0.5)

Note: The show parameter for this function is available in Mudlet 3.12+

stopSpeedwalk

stopSpeedwalk()

Stops a speedwalk started using speedwalk()

Available in Mudlet4.13+

local ok, err = stopSpeedwalk()
if not ok then
  cecho(f"\n<red>Error:<reset> {err}")
  return
end
cecho(f"\n<green>Success:<reset> speedwalk stopped")

unHighlightRoom

unHighlightRoom(roomID)

Unhighlights a room if it was previously highlighted and restores the rooms original environment color.

unsetRoomCharColor

unsetRoomCharColor(roomId)

Parameters

roomID:

Room ID to to unset char color to.

Removes char color setting from room, back to automatic determination based on room background lightness.

unsetRoomCharColor(2031)

Available in Mudlet4.11+

updateMap

updateMap()

Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.

@@ Line 141: / Line 141: @@
 ==addRoom==
-;addRoom(roomID)
-:Creates a new room with the given ID, returns true if the room was successfully created.
+;addRoom(roomID, areaID)
+:Creates a new room with the given room ID and area ID, returns true if the room was successfully created.
+;Parameters
+* ''roomID:''
+: Room ID to set the room as, manually assigned or from [[#createRoomID|createRoomID()]].
+* ''areaID:''
+: Area ID to set the room in, as returned by [[#getAreaTable|getAreaTable()]] or equivalents.
 {{note}} If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with [[#createRoomID|createRoomID()]] and associating your room IDs with Mudlets via [[#setRoomIDbyHash|setRoomIDbyHash()]] and [[#getRoomIDbyHash|getRoomIDbyHash()]]. The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge.

Difference between revisions of "Manual:Mapper Functions"

Revision as of 06:37, 24 December 2024

Mapper Functions

addAreaName

addCustomLine

addMapEvent

addMapMenu

addRoom

addSpecialExit

auditAreas

centerview

clearAreaUserData

clearAreaUserDataItem

clearMapSelection

clearMapUserData

clearMapUserDataItem

clearRoomUserData

clearRoomUserDataItem

clearSpecialExits

closeMapWidget

connectExitStub

createMapLabel

createMapImageLabel

createMapper

createRoomID

deleteArea

deleteMap

deleteMapLabel

deleteRoom

disableMapInfo

enableMapInfo

getAllAreaUserData

getAllMapUserData

getAllRoomEntrances

getAllRoomUserData

getAreaExits

getAreaRooms

getAreaTable

getAreaTableSwap

getAreaUserData

getCustomEnvColorTable

getCustomLines

getCustomLines1

getDoors

getExitStubs

getExitStubs1

getExitWeights

getGridMode

getMapEvents

getMapLabel

getMapLabels

getMapMenus

getMapSelection

getMapUserData

getMapZoom

getPath

getPlayerRoom

getRoomArea

getRoomAreaName

getRoomChar

getRoomCharColor

getRoomCoordinates

getRoomEnv

getRoomExits

getRoomHashByID

getRoomIDbyHash

getRoomName

getRooms

getRoomsByPosition

getRoomUserData

getRoomUserDataKeys

getRoomWeight

getSpecialExits

getSpecialExitsSwap

gotoRoom

hasExitLock

hasSpecialExitLock

highlightRoom

killMapInfo

loadJsonMap