Manual:Mapper Functions

Mapper Functions

These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be MUD-generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the MUD 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.

See also: deleteArea(), addRoom()

Example

local newId, err = addAreaName(string.random(10))

if newId == nil or newId < 1 or err then
  echo("That area name could not be added - error is: ".. err.."\n")
else
  cecho("<green>Created new area with the ID of "..newId..".\n")
end

addCustomLine

addCustomLine(roomID, id_to, direction, style, color, arrow)

See also: getCustomLines()

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 which to work properly must be an UPPERCASE string for the Normal exits, one of: "N", "NE", "E", "SE", "S", "SW", "W", "NW", "UP", "DOWN", "IN" or "OUT" or cased to match a Special exit - though if there is a clash the effects may not be what is expected {e.g. do not have a special exit called "OUT"}! Also note that this set of normal exit "keys" are not the same as those used for exit weights, doors or locks...!
• style: a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.
• 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.

Note: Available since Mudlet 3.0.

Examples

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

addCustomLine(1, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)

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

local areaid = addAreaName("my first area")
local newroomid = createRoomID()
addRoom(newroomid)
setRoomArea(newroomid, "my first area")
setRoomCoordinates(newroomid, 0, 0, 0)

addCustomLine(newroomid, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)

centerview(newroomid)

Note: At the time of writing there is no Lua command to remove a custom exit line and, for Normal exits in the X-Y plane, revert to the standard straight line between the start room and the end room (or colored arrow for out of area exits) however this can be done from the GUI interface to the 2D mapper.

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.

See also: addMapMenu(), removeMapEvent(), getMapEvents()

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 on clicking will send all the arguments.

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().

See also: addMapEvent(), removeMapEvent(), getMapEvents()

Example

addMapMenu("Favorites") -- will create a menu, favorites

addMapMenu("Favorites1234343", "Favorites", "Favorites")

The last line will create a submenu with the unique id Favorites123.. under Favorites with the display name of Favorites.

addRoom

addRoom(roomID)

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

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.

See also: createRoomID()

Example

local newroomid = createRoomID()
addRoom(newroomid)

addSpecialExit

addSpecialExit(roomIDFrom, roomIDTo, command)

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

See also: clearSpecialExits()

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)

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.

See also: updateMap()

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.

See also: setAreaUserData(), getAllAreaUserData(), clearAreaUserDataItem(), clearRoomUserData()

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

Note: Available since Mudlet 3.0.

clearAreaUserDataItem

clearAreaUserDataItem(areaID,key)

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

See also: setAreaUserData(), clearAreaUserData(), clearRoomUserDataItem()

Note: Available since Mudlet 3.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

clearMapUserData

clearMapUserData()

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

See also: setMapUserData(), clearRoomUserData(), clearAreaUserData()

Note: Available since Mudlet 3.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

clearUserDataItem(mapID,key)

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

See also: setMapUserData(), clearMapUserData(), clearAreaRoomUserData()

Example

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

display(clearMapUserDataItem("doorname_up"))
true

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

display(clearMapUserDataItem("doorname_up"))
false

Note: Available since Mudlet 3.0.

clearRoomUserData

clearRoomUserData(roomID)

Clears all user data from a given room.

See also: setRoomUserData(), clearRoomUserDataItem():

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.

See also: setRoomUserData(), clearRoomUserData(), clearAreaUserDataItem()

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

Note: Available since Mudlet 3.0.

As a work around for the absence of this and some other room user data commands in prior versions {which only possesses the clearRoomUserData() command but does not have anything to find out and preserve what data key-value pairs might have been used from other packages}, a suggested work around is to use a setRoomUserData(key,"") to empty any unwanted data and to treat data items with empty values the same as non-existent data items - when the user updates to a version with these commands a script could then detect and purge data items with keys that it is concerned with but which have only an empty string as a value...

clearSpecialExits

clearSpecialExits(roomID)

Removes all special exits from a room.

See also: addSpecialExit()

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

connectExitStub

connectExitStub(fromID, direction or toID[, optional 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 or toID:

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

• toID:

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

See also: setExitStub(), getExitStubs()

Example

-- try and connect all stubs that are in a room
local stubs = getExitStubs(roomID)
  if stubs then
    for i,v in pairs(stubs) do
    connectExitStub(roomID, v)
  end
end

createMapLabel

labelID = createMapLabel(areaID, text, posx, posy, posz, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue, zoom, fontSize, showOnTop, noScaling)

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

See also: getMapLabel(), getMapLabels()

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 room coordinates.

• fgRed, fgGreen fgBlue:

Foreground color or text color of the label.

• bgRed, bgGreen bgBlue:

Background color of the label.

• zoom:

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:

Size of the font of the text. Default is 50.

• showOnTop:

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.

• noScaling:

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.

See also: deleteMapLabel

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)

createMapImageLabel

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

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.

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.

See also: deleteMapLabel

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 width of the image
-- 100 is how much we zoom it by, 1 would be no zoom
-- and lastly, false to make it go below our rooms
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false)

createMapper

createMapper(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.

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)

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.

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):

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.

Note: minimumStartingRoomId is available since Mudlet 3.0.

See also: addRoom()

deleteArea

deleteArea(areaID or areaName)

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

See also: addAreaName()

Parameters

• areaID:

Area ID to delete.

• areaName:

Area name to delete (available since Mudlet 3.0).

Example

-- delete by areaID
deleteArea(23)
-- or since Mudlet 3.0, by area name
deleteArea("Big city")

deleteMapLabel

deleteMapLabel(areaID, labelID)

Deletes a map label from a specfic area.

See also: createMapLabel()

Example

deleteMapLabel(50, 1)

deleteRoom

deleteRoom(roomID)

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

Example

deleteRoom(335)

exportAreaImage

exportAreaImage(areaID)

Exports the area as an image into your profile's directory.

Example

-- save the area with ID 1 as a map
exportAreaImage(1)

Note: This command is currently inoperable in current 3.0+ versions of Mudlet.

getAllMapUserData

getAllMapUserData()

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

See also: getMapUserData()

Example

display(getAllMapUserData())
--might result in:--
{
  description = [[This map is about so and so game]],
  author = "Bob",
  ["last updated"] = "December 5, 2020"
}

Note: Available in Mudlet 3.0 - requires Mudlet Map format 17 or later to save which has not yet been made the default as it is not compatible with Mudlet 2.1 and will be rejected by that version. The format can be manually set to be the upgraded one in recent Mudlet development and release 3.0 previews via an option on the "Special Options" tab of the "Profile Preferences" (Options) dialogue. Attempting to use MapUserData or AreaUserData with the current default (backwards compatible) format (16) will produce a warning the first time in a session that a value is set and each time the Map file is saved. Once this change has been made it will persist but leave an advisory message on loading in current Mudlet versions.

getAllRoomUserData

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.

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"
}

Note: Available in Mudlet 3.0.

getAreaExits

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.

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.

See also: setExit(), getRoomExits()

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.

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 ipairs(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

getAreaTable()

Returns a key(area name)-value(area id) table with all known areas and their IDs. 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

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

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.

Example

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

Note:

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

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.

See also: setCustomEnvColor()

Example

{
  envid1 = {r,g,b},
  envid2 = {r,g,b}
}

getCustomLines

getCustomLines(roomID)

See also: addCustomLine()

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.

Note: Available since Mudlet 3.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
      }
    }
  }
}

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.

See also: setDoor()

Example

-- an example that displays possible doors in room 2334
local doors = getDoors(2334)

if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end

local door_status = {"open", "closed", "locked"}

for direction, door in pairs(doors) do
  cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")
end

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.

See also: setExitStub(), connectExitStub(), getExitStubs1()

Example

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

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.

See also: setExitWeight()

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().

See also: addMapMenu(), removeMapEvent(), 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")

display(getMapEvents()) -- displays the events above

Note: Available in Mudlet 3.3

getMapLabel

labelinfo = getMapLabels(areaID, labelID)

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

See also: createMapLabel(), getMapLabels()

Example

lua getMapLabels(1658987)
table {
  1: 'no text'
  0: 'test'
}

lua getMapLabel(1658987, 0)
table {
  'Y': -2
  'X': -8
  'Z': 11
  'Height': 3.9669418334961
  'Text': 'test'
  'Width': 8.6776866912842
}

lua getMapLabel(1658987, 1)
table {
  'Y': 8
  'X': -15
  'Z': 11
  'Height': 7.2520666122437
  'Text': 'no text'
  'Width': 11.21900844574
}

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.

See also: createMapLabel(), getMapLabel()

Example

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

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

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.

See also: getAllMapUserData(), setMapUserData()

Example

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

Note: Available in Mudlet 3.0

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 speedWalkPath table is set to all of the directions that have to be taken to get there, and the global speedWalkDir 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.

Example

-- check if we can go to room 155 from room 34 - if yes, go to it
if getPath(34,155) then
  gotoRoom(155)
else
  echo("\nCan't go there!")
end

getRoomArea

areaID = 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

areaname = getRoomAreaName(areaID)

Returns the area name for a given area id; logically it ought to return the area name for a given room id (or room name) but revising it so it does that would break existing scripts.

Example

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

getRoomCoordinates

x,y,z = getRoomCoordinates(room ID)

Returns the room coordinates of the given room ID.

Example

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

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

funtion checkID(id)
  echo(strinf.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.

See also: getSpecialExits()

Example

table {
  'northwest': 80
  'east': 78
}

Here's a practical example that queries the rooms around you and searched for one of the water environments (the number would depend on how it was mapped):

local exits = getRoomExits(mycurrentroomid)
for direction,num in pairs(exits) do
  local env_num = getRoomEnv(num)
  if env_num == 22 or env_num == 20 or env_num == 30 then
    print("There's water to the "..direction.."!")
  end
end

getRoomIDbyHash

roomID = getRoomIDbyHash(hash)

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

Example

-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177
_id1 = getRoomIDbyHash( "5dfe55b0c8d769e865fd85ba63127fbc" );
if _id1 == -1 then 
  _id1 = createRoomID()
  setRoomIDbyHash( _id1, "5dfe55b0c8d769e865fd85ba63127fbc" )
  addRoom( _id )
  setRoomCoordinates( _id1, 0, 0, -1 )
end

getRoomName

roomName = 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())

getRoomsByPosition

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.

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"))

Note: code around 3.0 preview versions "delta" and "epsilon" were revised and would return both a Lua nil and an error message should the roomID not actually exist or if the key was not found in the user data for that room. This would break existing scripts that relied upon getting an empty string i.e. "" in either of those case even though it is possible to store such a string against a key in the room user data. Pending changes will restore the prior behavior when getRoomUserData is provided with two arguments and new scripts will instead be recommended to use:

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.

See also: clearRoomUserData(), clearRoomUserDataItem(), getAllRoomUserData(), getRoomUserDataKeys(), searchRoomUserData(), setRoomUserData()

Example

<lua>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</syntaxhighlight>

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!

See also: clearRoomUserData(), clearRoomUserDataItem(), getAllRoomUserData(), getRoomUserData(), searchRoomUserData(), setRoomUserData()

Example

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

Note: Available since Mudlet 3.0.

getRoomWeight

room weight = getRoomWeight(roomID)

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

See also: setRoomWeight()

Example

display("Original weight of room 541: "..getRoomWeight(541)
setRoomWeight(541, 3)
display("New weight of room 541: "..getRoomWeight(541)

getSpecialExits

exits = getSpecialExits(roomID)

Returns a roomid - command table of all special exits in the room. If there are no special exits in the room, the table returned will be empty.

See also: getRoomExits()

Example

getSpecialExits(1337)

-- results in:
--[[
table {
  12106: 'faiglom nexus'
}
]]

getSpecialExitsSwap

exits = 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 :(".

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"))

See also: lockExit()

hasSpecialExitLock

status = hasSpecialExitLock(from roomID, to roomID, command)

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

-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command
lockSpecialExit(17463, 7814, 'enter feather', true)

-- see if it is locked: it will say 'true', it is
display(hasSpecialExitLock(17463, 7814, 'enter feather'))

highlightRoom

highlightRoom( id, r1,g1,b1,r2,g2,b2, radius, alpha1, alpha2)

Highlights a room with the given color, which will override it's 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. highlightRadius is the radius for the highlight circle - if you don't want rooms beside each other to over lap, use 1 as the radius. alphaColor1 and alphaColor2 are transparency values from 0 (completely transparent) to 255 (not transparent at all).

See also: unHighlightRoom()

Note: Available since Mudlet 2.0 final release

-- color room #351 red to blue
local r,g,b = unpack(color_table.red)
local br,bg,bb = unpack(color_table.blue)
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)

getAllRoomEntrances

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.

Note: Available since Mudlet 3.0.

Example

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

See also: getRoomExits()

loadMap

boolean = 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 download-able maps for their MUDs.

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

See also: saveMap()

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

lockExit

lockExit(roomID, direction, lock = true/false)

Locks a given exit from a room (which means that unless all exits in the incoming room are locked, it'll still be accessible). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").

Example

-- lock the east exit of room 1201 so we never path through it
lockExit(1201, 4, true)

See also: hasExitLock()

lockRoom

lockRoom (roomID, lock = true/false)

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

See also: roomLocked()

Example

lockRoom(1, true) -- locks a room if from being walked through when speedwalking.
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.

lockSpecialExit

lockSpecialExit (from roomID, to roomID, special exit command, lock = true/false)

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

See also: hasSpecialExitLock(), lockExit(), lockRoom()

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

resetRoomArea

resetRoomArea (areaID)

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.

See also: setRoomArea(), getRoomArea()

Example

resetRoomArea(3143)

removeMapEvent

removeMapEvent (event name)

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

See also: addMapEvent(), addMapMenu(), getMapEvents()

Example

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

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.

See also: lockRoom()

Example

echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))

saveMap

saveMap(location)

Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work.

See also: loadMap()

Example

local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")
if not savedok then
  echo("Couldn't save :(\n")
else
  echo("Saved fine!\n")
end

searchAreaUserData

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 name / room number)

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.

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

Example

display(searchRoom("master"))

--[[ would result in:
table {
  17463: 'in the branches of the Master Ravenwood'
  3652: 'master bedroom'
  10361: 'Hall of Cultural Masterpieces'
  6324: 'Exhibit of the Techniques of the Master Artisans'
  5340: 'office of the Guildmaster'
  (...)
  2004: 'office of the guildmaster'
  14457: 'the Master Gear'
  1337: 'before the Master Ravenwood Tree'
}
]]

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

Note: Additional parameters are available since Mudlet 3.0:

searchRoom (room name, [case-sensitive [, exact-match]])

Additional Parameters

• case-sensitive:

If true forces a case-sensitive search to be done on with the supplied room name argument, if false case is not considered.

• exact-match:

If true forces an exact match rather than a sub-string match, with a case sensitivity as set by previous option.

Example

display(searchRoom("North road",false,false))
-- could result in: --
{
  [3094] = "North Road",
  [3031] = "North Road",
  [3063] = "The North Road",
  [3095] = "North Road",
  [3097] = "North Road",
  [3098] = "North Road",
  [6229] = "Grassy Field By North Road",
  [3099] = "Bend in North Road",
  [3100] = "Bend in North Road",
  [3132] = "North Road",
  [3101] = "North Road",
  [3133] = "North Road",
  [3102] = "North Road",
  [3134] = "North Road",
  [3103] = "North Road",
  [3135] = "North Road",
  [3104] = "North Road",
  [3136] = "North Road",
  [3105] = "North Road",
  [3042] = "North Road",
  [3106] = "North Road",
  [3138] = "North Road",
  [3043] = "North Road",
  [3107] = "North Road",
  [3108] = "Bend in North Road",
  [3077] = "The North Road",
  [3109] = "Bend in North Road",
  [3046] = "North Road",
  [3110] = "North Road",
  [3047] = "The North Road",
  [3111] = "North Road",
  [3143] = "North Road",
  [3048] = "The North Road",
  [3112] = "Bend in North Road",
  [3144] = "North Road",
  [3049] = "The North Road",
  [3145] = "North Road",
  [3050] = "The North Road",
  [3114] = "Bend in North road",
  [3146] = "Bend in the North Road",
  [3115] = "North road",
  [3020] = "North road",
  [3116] = "North Road",
  [3148] = "Bend in the North Road",
  [3117] = "North road",
  [3149] = "North road",
  [3118] = "North road",
  [3150] = "North road",
  [3025] = "North road",
  [3027] = "North road",
  [3119] = "North road",
  [3151] = "North road",
  [3026] = "North road",
  [3088] = "The North Road South of Taren Ferry",
  [3120] = "North Road",
  [3152] = "North Road",
  [3029] = "North Road",
  [3089] = "The North Road",
  [3121] = "North Road",
  [3153] = "North Road",
  [3028] = "North Road",
  [3090] = "The North Road",
  [3122] = "North Road",
  [3154] = "North Road",
  [3017] = "North Road",
  [3091] = "The North Road",
  [3123] = "North Road",
  [3155] = "North Road",
  [3016] = "North Road",
  [3092] = "The North Road",
  [3019] = "North Road",
  [3156] = "North Road",
  [3018] = "North Road",
  [3093] = "North Road",
  [3021] = "North Road",
  [3022] = "North Road"
}

-- but some of the above have different cases: --
display(searchRoom("North road",true,false))
{
  [3151] = "North road",
  [3114] = "Bend in North road",
  [3115] = "North road",
  [3026] = "North road",
  [3117] = "North road",
  [3020] = "North road",
  [3118] = "North road",
  [3119] = "North road",
  [3025] = "North road",
  [3150] = "North road",
  [3027] = "North road",
  [3149] = "North road"
}

-- only some are a plain "north road" in either case: --
lua searchRoom("North road",false,true)
{
  [3106] = "North Road",
  [3122] = "North Road",
  [3138] = "North Road",
  [3020] = "North road",
  [3154] = "North Road",
  [3107] = "North Road",
  [3115] = "North road",
  [3123] = "North Road",
  [3021] = "North Road",
  [3155] = "North Road",
  [3116] = "North Road",
  [3132] = "North Road",
  [3025] = "North road",
  [3022] = "North Road",
  [3093] = "North Road",
  [3101] = "North Road",
  [3046] = "North Road",
  [3117] = "North road",
  [3027] = "North road",
  [3133] = "North Road",
  [3026] = "North road",
  [3149] = "North road",
  [3094] = "North Road",
  [3102] = "North Road",
  [3110] = "North Road",
  [3118] = "North road",
  [3029] = "North Road",
  [3134] = "North Road",
  [3016] = "North Road",
  [3150] = "North road",
  [3095] = "North Road",
  [3103] = "North Road",
  [3111] = "North Road",
  [3119] = "North road",
  [3028] = "North Road",
  [3135] = "North Road",
  [3143] = "North Road",
  [3151] = "North road",
  [3031] = "North Road",
  [3104] = "North Road",
  [3017] = "North Road",
  [3120] = "North Road",
  [3019] = "North Road",
  [3136] = "North Road",
  [3144] = "North Road",
  [3152] = "North Road",
  [3097] = "North Road",
  [3105] = "North Road",
  [3018] = "North Road",
  [3121] = "North Road",
  [3043] = "North Road",
  [3042] = "North Road",
  [3145] = "North Road",
  [3153] = "North Road",
  [3098] = "North Road",
  [3156] = "North Road"
}

-- and less are an exact match, technically, this 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:--
lua searchRoom("North road",true,true)
{
  [3151] = "North road",
  [3115] = "North road",
  [3026] = "North road",
  [3117] = "North road",
  [3020] = "North road",
  [3118] = "North road",
  [3119] = "North road",
  [3025] = "North road",
  [3150] = "North road",
  [3027] = "North road",
  [3149] = "North road"
}

searchRoomUserData

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:

See also: clearRoomUserData(), clearRoomUserDataItem(), getAllRoomUserData(), getRoomUserData(), #getRoomUserDataKeys(), setRoomUserData()

searchRoomUserData(key, value)

Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key". Due to the lack of previous enforcement it is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.

searchRoomUserData(key)

Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key". Due to the lack of previous enforcement it is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.

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.

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
}
]]

Note: Available since Mudlet 3.0.

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: areaName is available since Mudlet 3.0.

See also: deleteArea(), addAreaName()

Example

setAreaName(2, "My city")

-- available since Mudlet 3.0
setAreaName("My old city name", "My new city name")

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.

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

Note: While 3.0 makes this function available, it is unable to load the prerequisite map formats 17 and 18 that can store area-level data - so hold off on using this function for now.

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(34, "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.

See also: getCustomEnvColorTable(), setRoomEnv()

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.

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 pathfinding. You can use the information to change 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!

See also: getDoors()

Parameters

• roomID:

Room ID to to create the door in.

• exitCommand:

The cardinal direction for the door is in - it can be one of the following: n, e, s, w, ne, se, sw, ne. {Plans are afoot to add support for doors on the other normal exits: up, down, in and out, and also on special exits - though more work will be needed for them to be shown in the mapper.} It is important to ONLY use these direction codes as others e.g. "UP" will be accepted - because a special exit could have ANY name/lua script - but it will not be associated with the particular normal exit - recent map auditing code about to go into the code base will REMOVE door and other room exit items for which the appropriate exit (or stub) itself is not present, so in this case, in the absence of a special exit called "UP" that example door will not persist and not show on the normal "up" exit when that is possible later on.

• doorStatus:

The door status as a number - 0 means no (or remove) door, 1 means open door (will draw a green square on exit), 2 means closed door (yellow square) and 3 means locked door (red square).

Example

-- make a door on the east exit of room 4234 that is currently open
setDoor(4234, 'e', 1)

-- remove a door from room 923 that points north
setDoor(923, 'n', 0)

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.

Example

-- alias pattern: ^exit (\d+) (\d+) (\w+)$
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north

if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then
  echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))
else
  echo("Failed to set the exit.\n")
end

This function can also delete exits from a room if you use it like so:

<lua>setExit(from roomID, -1, direction)</syntaxhighlight>

- which will delete an outgoing exit in the specified direction from a room.

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 number, short direction name ("nw") or long direction name ("northwest").

• set/unset:

A boolean to create or delete the exit stub.

See also: getExitStubs(), connectExitStub()

Example

Create an exit stub to the south from room 8:

setExitStub(8, 6, true)

.. or using an exitmap (see Mapping_script#Translating_directions):

setExitStub(8, exitmap.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: e,s,w,n,ne,se,sw,ne,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 increasing 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.

See also: getExitWeights()

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.

Example

setGridMode(55, true) -- set area with ID 55 to be in 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.

See also: clearMapUserData(), clearMapUserDataItem(), getAllMapUserData(), getMapUserData()

Note: While 3.0 makes this function available, it is unable to load the prerequisite map formats 17 and 18 that can store map-level data - so hold off on using this function for now.

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)

Zooms the map in to a given zoom level. 1 is the closest you can get, and anything higher than that zooms the map out. Call centerview() after you set the zoom to refresh the map.

Example

setMapZoom(10) -- zoom to a somewhat acceptable level, a bit big but easily visible connections

setModulePriority

setModulePriority(module name, priority #)

Sets the module priority on a given module as a number - the module priority determines the order modules are loaded in, which can be helpful if you have ones dependent on each other. This can also be set from the module manager window.

See also: getModulePriority()

setModulePriority("mudlet-mapper", 1)

setRoomArea

setRoomArea(roomID, newAreaID)

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.

See also: resetRoomArea()

setRoomChar

setRoomChar(roomID, character)

Designed for an area in grid mode, this will set a single character to be on a room. You can use "_" to clear it.

Example

setRoomChar(431, "#")

setRoomChar(123. "$")

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.

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

Example

-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$
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)

You can make them relative as 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.

See also: setCustomEnvColor()

Example

setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34

setRoomIDbyHash

setRoomIDbyHash(roomID, hash)

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

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.

See also: clearRoomUserData(), clearRoomUserDataItem(), getAllRoomUserData(), getRoomUserData(), searchRoomUserData()

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, "ourdoors", "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().

See also: getRoomWeight()

Example

setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it

speedwalk

speedwalk(dirString, backwards, delay)

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 mud 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)

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- explicitly indicate true or false for the reverse flag.)

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 Mud 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. (See the link at the beginning of my post for something like that.)

Likewise, if your Mud 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 <lua>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight>

unHighlightRoom

unHighlightRoom(roomID)

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

See also: highlightRoom()

Note: Available since Mudlet 2.0 final release

Example

unHighlightRoom(4534)

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.

See also: centerview()

Example

-- delete a some room
deleteRoom(500)
-- now make the map show that it's gone
updateMap()