mudlet客户端地图(map)使用指南 - MUD.REN

https://wiki.mudlet.org/w/Manual:Mapper_Functions

mudlet 提供了大量画地图相关函数，方便实现游戏地图和导航。

重要的map函数

`addAreaName(areaName)`

添加新区域名称并返回新名称的新区域ID(正整数)。 如果名称已经存在，旧版本的Mudlet返回-1，v3.0以后的版本代码将返回nil和错误消息。

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(roomID, id_to, direction, style, color, arrow)`

添加一个新的或替换2d地图组件上的指定的房间之间的自定义出口路径线。

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

在地图组件右键菜单上增加自定义事件

`addMapMenu(uniquename, parent, display name)`

在地图组件上增加右键菜单

`addRoom(roomID)`

使用给定的ID创建一个新的房间，如果成功创建了房间，则返回true。

local newroomid = createRoomID()
addRoom(newroomid)

`addSpecialExit(roomIDFrom, roomIDTo, moveCommand)`

创建一个从一个房间到另一个房间的特殊出口，将使用给定的命令通过它们。

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

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

`auditAreas()`

在整个地图上启动一致性检查：所有房间，区域及其组成, 并将结果输出到屏幕和日志文件以供以后查看。当您第一次打开地图时，这也会自动完成，因此甚至不需要手动调用这个函数。

`centerview (roomID)`

将地图视图居中到给定的房间ID上。 地图必须打开才能生效, 这个功能也可以用来看一个区域的地图。

`clearAreaUserData(areaID)`

清除给定区域的所有用户数据。 请注意，这不会影响区域房间用户数据。

`clearAreaUserDataItem(areaID, key)`

从给定区域的用户数据中删除特定的键和值。

`clearRoomUserData(roomID)`

清除给定房间的所有用户数据。如果从指定的房间中删除了任何数据，则返回布尔值true，如果没有要删除的内容，则返回false。

`clearRoomUserDataItem(roomID, key)`

从给定房间的用户数据中删除特定的键和值。如果根据给定房间的用户数据中的键找到数据并将其删除，则返回布尔值true，如果数据中不存在指定的键，则返回false。 如果找不到指定ID的房间，则返回nil。

`clearSpecialExits(roomID)`

删除房间的所有特殊出口。

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

关闭地图组件

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

使用匹配的出口存根连接现有房间。 如果你只给它一个roomID和一个方向，它会自动判断相应的方向并链接。 您也可以只指定从和到房间Id，它会巧妙地使用正确的方向链接。 最后，您可以指定所有三个参数-fromID，toID和方向（按该顺序），或者使用setExit()来获得相同的效果。

`createRoomID([minimumStartingRoomId])`

返回可用于创建新房间的最低房间ID。 如果您的地图使用的房间ID有间隙(通常是删除房间造成)，则此功能将在创建更高的Id之前先使用间隙。

`deleteArea(areaID or areaName)`

删除给定区域及其中的所有房间。 成功时返回true，否则返回nil+错误消息。

`deleteRoom(roomID)`

删除一个单独的房间，并取消链接所有通向和离开它的出口。

`getAllAreaUserData(areaID)`

返回存储在给定区域ID中的所有用户数据项；如果没有存储数据，将返回一个空表；如果没有具有该ID的区域，则返回nil。

`getAllMapUserData()`

返回存储在地图级别的所有用户数据项；如果没有存储数据，将返回一个空表。

`getAllRoomEntrances(roomID)`

返回通往此房间的正常出口和特殊出口的索引列表。 在双向出口的情况下，这将报告与get Room Exists()完全相同的房间，但此函数也能够拾取进入房间的单向出口。

`getAllRoomUserData(roomID)`

返回存储在给定房间ID中的所有用户数据项；如果没有存储数据，将返回一个空表；如果没有存储该ID的房间，将返回nil。

`getAreaExits(areaID, showExits)`

返回给定区域中具有通向其他区域（即边界房间）的出口的房间的表（索引或键值）。

`getAreaRooms(area id)`

返回一个索引表，其中包含给定区域ID的所有房间Id，如果不存在这样的区域，则返回nil。

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

返回包含所有已知区域及其Id的key（区域名称）-value（区域id）表。

`getAreaTableSwap()`

返回包含所有已知区域及其Id的key（区域id）-value（区域名称）表。

`getAreaUserData(areaID, key)`

返回针对给定区域ID号的给定键存储的特定数据项。

`getCustomEnvColorTable()`

返回具有自定义环境颜色的表，其中键是环境ID，值是rgb值的索引表。

`getCustomLines(roomID)`

返回指定房间的自定义出路路径线的资料

`getDoors(roomID)`

返回以基数方向为键，门值为数字的键值表。 如果房间里没有门，它会返回一张空表。

`getExitStubs(roomid)`

返回指定房间的出口存根(还没有连接具体房间的出口), 值为指定方向的索引(从0开始)。

`getExitStubs1(roomid)`

返回指定房间的出口存根(还没有连接具体房间的出口), 值为指定方向的索引(从1开始)。

`getExitWeights(roomid)`

返回房间具有的出口权重的键值表，以方向或特殊出口作为键，以值作为出口权重。 如果尚未设置方向的权重，则不会列出该权重。

`getGridMode(areaID)`

使用这个来查看一个特定的区域是网格还是荒野视图模式设置。 返回值为true/false

`getMapEvents()`

返回已注册的地图事件

`getMapMenus()`

返回自定义的地图组件右键菜单列表

`getMapSelection()`

返回一个表格，其中包含2D mapper 中当前鼠标选择的房间的详细信息。

`getMapUserData( key )`

返回直接存在地图中的指定key的数据, 如果地图数据中没有包含此键的数据，则将返回nil+错误消息。

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

`getPath(roomID from, roomID to)`

如果两个房间Id之间的路径是可能的，则返回布尔值true/false 和路径总权重(所有权重加起来)。 如果是，全局speedWalkDir表将设置为到达那里必须采取的所有方向，全局speedWalkPath表将设置为您在途中遇到的所有roomid，speedWalkWeight将返回所有房间权重。

`getPlayerRoom()`

返回由centerview()设置的当前玩家的位置。

`getRoomArea(roomID)`

返回给定房间ID的区域ID。 要获取区域名称，您可以根据getAreaTable()函数给出的数据检查区域ID，或者使用getRoomAreaName()函数。

`getRoomAreaName(areaID or areaName)`

返回给定区域id的区域名称；或给定区域名称的区域id。

`getRoomChar(roomID)`

返回给定房间id的标记符号。

`getRoomCoordinates(roomID)`

返回给定房间ID的房间坐标。

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(roomID)`

返回房间的环境ID。 mapper不存储环境名称，因此您需要自己跟踪哪个ID是什么名称。

`getRoomExits(roomID)`

返回键索引中房间当前已知的非特殊出口，格式为：exit=exitroomid。

`getRoomHashByID(roomID)`

返回与mapper的给定房间ID关联的房间哈希。 这主要适用于使用哈希而不是房间Id的游戏, 它可用于共享地图数据，而不共享地图本身, 如果没有找到房间，则返回nil。

`getRoomIDbyHash(hash)`

返回与mapper中的给定哈希关联的房间ID。 这主要是用于使用哈希而不是房间ID的游戏(如炎黄和Avalon.de)如果没有房间ID与哈希匹配，则返回-1。

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

`getRoomName(roomID)`

返回给定房间id的房间名称。

`getRooms()`

以房间id-房间名称格式返回整个地图中所有房间的列表。

-- 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(areaID, x,y,z)`

返回给定区域中给定坐标处所有房间的索引表，如果没有，则返回空表。 此功能可用于检查某个房间是否存在于某个坐标处。注意:返回的表从0开始索引，而不是lua通常的1开始索引，这意味着使用#来计算返回表的大小会产生错误的结果-可用 table.size() 代替。

`getRoomUserData(roomID, key)`

返回使用给定键（字符串）存储在给定房间中的用户数据值（字符串），如果未存储则返回""。 使用 `setRoomUserData()` 函数设置用户数据。

`getRoomUserDataKeys(roomID)`

返回存储在给定房间ID中的用户数据项的所有键；如果没有存储数据，将返回一个空表；如果没有存储该ID的房间，将返回nil

`getRoomWeight(roomID)`

返回房间的权重。 默认情况下，所有新房间的权重为1。

`getSpecialExits(roomID[, listAllExits])`

返回包含房间中特殊出口的命令和出口锁定状态的子表的roomid表。 如果房间里没有特殊的出口，返回空表。

{
  [123] = {
    westup = "0"
  }
}

`getSpecialExitsSwap(roomID)`

和`getSpecialExits`类似,只是返回的是`命令-出口roomID`的格式

{
  westup = 123
}

`gotoRoom (roomID)`

从你当前房间快速移动到路径连通的目标房间, 这个必须开启地图才能工作,否则会提示找不到路径.

`hasExitLock(roomID, direction)`

返回房间指定出口是否是上锁的(true/false), 方向可以是出口索引或全拼或缩写,如:3 或 northwest 或 nw

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

`hasSpecialExitLock(from roomID, to roomID, moveCommand)`

返回true或false，具体取决于从房间引出的给定出口是否被锁定。 `moveCommand`是通过出口要采取的指令。

`loadJsonMap(pathFileName)`

以文本(JSON)格式加载地图，它确实比加载通常的地图文件（.dat 二进制格式）慢很多，所以它会显示一个进度条。

loadJsonMap(getMudetHomeDir() .. "/map.json")

`loadMap(file location)`

从给定位置加载地图文件。 地图文件必须是Mudlet的格式-使用saveMap()保存，或者，从Mudlet3.0开始，它可能是一个MMP XML地图，符合I.R.E.用于其MUD游戏的可下载地图的结构。

`lockExit(roomID, direction, lockIfTrue)`

锁定房间的给定出口（这意味着除非进入房间的所有出口都被锁定，否则它仍然可以访问）。 方向可以指定为数字，短方向名称（"nw"）或长方向名称（"northwest"）。

`lockRoom (roomID, lockIfTrue)`

锁定房间，快速行走不会经过被锁定的房间。

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

锁定一个给定的特殊出口，快速行走不会经过锁定的出口。

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

打开游戏地图组件,可指定参数.

`pauseSpeedwalk()`

暂停一个由`speedwalk()`执行的快速行走

`registerMapInfo(label, function)`

增加额外的自定义信息到地图组件上

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

file

registerMapInfo("Alert", function() 
  if gmcp.Char.Vitals.hp < 1000 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()`

继续执行使用`pauseSpeedwalk()`暂停的快速行走

`removeCustomLine(roomID, direction)`

移除指定房间指定方向的自定义出口路径线

`removeMapEvent(event name)`

移除自定义的地图组件事件

`removeMapMenu(menu name)`

移动自定义的地图组件右键菜单

`removeSpecialExit(roomID, command)`

移除指定房间的特殊出口

`resetRoomArea (roomID)`

将房间从给定区域取消分配。 未分配时，其区域ID将为-1。

`roomExists(roomID)`

判断指定房间ID是否存在

`roomLocked(roomID)`

判断指定房间是否被锁定

`saveJsonMap([pathFileName])`

保存json格式的地图，这个花费的时间要比保存二进制格式(.dat)的长，所以在保存时会有进度提示。

saveJsonMap(getMudletHomeDir() .. "/map.json")

`saveMap([location], [version])`

保存二进制格式的地图

saveMap(getMudletHomeDir().."/map.dat")

`searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])`

搜索保存在地区中的用户自定义数据

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

根据ID查询房间名称，或根据名称查找房间，这会返回一个格式为 roomID=roomName 的表。

`searchRoomUserData([key, [value]])`

从所有房间中查找用户自定义资料，可以查找key、value

`setAreaName(areaID or areaName, newName)`

为区域命名或重命名，需要先用`addAreaName()`创建地区。

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

设置存在区域中的用户字定义内容

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

自定义指定环境在地图组件上的颜色

`setDoor(roomID, exitCommand, doorStatus)`

为房间指定出口设置门，`doorStatus`可以是0：没有门、1：开着的门、2：关着的门、3：锁着的门

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

-- 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(from roomID, to roomID, direction)`

设置房间标准出口（`n, ne, nw, e, w, s, se, sw, u, d, in, out`）的目标房间，出口可以是缩写、全拼或索引数字。设置出口时如果有设置stub, 会自动删除stub。

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

如果`to roomID`为`-1`，可以删除房间指定方向的出口：

setExit(from roomID, -1, direction)

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

`setExitStub(roomID, direction, set/unset)`

增加或移除指定房间指定方向的出口存根标记，方便将来为这个出口连接房间，第三个参数是`true`为增加出口标识，`false`为移除。

`setExitWeight(roomID, exitCommand, weight)`

设置出口权重，所有出口默认权重为0，在寻路时会优先选择权重高的出口。

`setGridMode(areaID, true/false)`

设置指定地区地图显示是否为网格模式。

`setMapZoom(zoom)`

设置地图组件的缩放比例

`setRoomArea(roomID, newAreaID or newAreaName)`

设置房间所属地图，地区可以是地区ID或Name

`setRoomChar(roomID, character)`

设置房间在地图组件上的标志

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

`setRoomCharColor(roomId, r, g, b)`

设置房间标志的颜色

`setRoomCoordinates(roomID, x, y, z)`

设置房间的在地图组件上的坐标

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

`setRoomEnv(roomID, newEnvID)`

设置房间的环境ID，环境ID是由你自己定义的数字，如数字1代表山路、数字2代表河流，可以设置有相同环境ID的房间有一样的颜色显示。

`setRoomIDbyHash(roomID, hash)`

设置房间的hash，hash是唯一的，如果把二个房间设置相同的hash，后设置的会取代先设置的

`setRoomName(roomID, newName)`

设置房间显示名称

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

设置房间中的用户自定义参数

`setRoomWeight(roomID, weight)`

设置房间的权重，默认情况下所有房间的权重都为1，权重越高的房间在寻路时越优先使用。如果想在寻路时不选择某个房间，请使用`lockRoom()`锁定。

`speedwalk(dirString, backwards, delay, show)`

快速行走

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.

`stopSpeedwalk()`

停止快速行走

`unsetRoomCharColor(roomId)`

取消对房间标记的颜色设置

`updateMap()`

更新地图显示，如果你通过脚本修改了地图，想马上生效，可使用此函数。

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

画地图

使用generic_mapper

Mudlet客户端内置generic_mapper地图脚本，可以方便自动画地图,玩家不需要复杂的操作，具体操作介绍请看这里：使用Mudlet内置地图扩展包generic_mapper画地图