mudlet客户端地图(map)使用指南

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

相关全局变量

speedWalkDir、speedWalkPath、speedWalkWeight

画地图

相关函数

前面介绍的地图相关的函数很多,但要画地图,核心函数如下:

-- 创建环境地区
setAreaName(areaID, areaname)
-- 创建房间ID,默认为最小可用ID,从1开始,自动累加
local roomID = createRoomID()
-- 增加一个房间并绑定ID
addRoom(roomID)
-- 设置房间所在地区
setRoomArea(roomID, areaID)
-- 定位到指定房间
centerview(roomID)

-- 设置房间名称
setRoomName(roomID, name)
-- 设置房间在地图上的坐标,如不设置坐标则默认为(0,0,0),房间会重叠在一起
setRoomCoordinates(roomID,x,y,z)
-- 设置房间出口,只支持 n, ne, nw, e, w, s, se, sw, u, d, in, out 和对应的全称英文,from room到to room之间会有一个方向箭头,如果是双向连接,则为一条连接2个房间的直线
setExit(from roomID, to roomID, direction)

-- 以上是100%需要的函数,以下是多数情况非常有用的函数

-- 如果房间出口连接是特殊指令,如渡口之间的`yell boat`,需要用addSpecialExit指令
addSpecialExit(roomIDFrom, roomIDTo, moveCommand)
-- 设置房间出口方向,注意常规出口只支持 n, ne, nw, e, w, s, se, sw, u, d, in, out 和对应的全称英文
-- ExitStub只是告诉你这个方向有出口,但还没有连接到对应的room
setExitStub(roomID, v,false)
-- 通过ExitStub连接二个房间
connectExitStub(fromID, direction) --or connectExitStub(fromID, toID, [direction])
-- 获取房间坐标
getRoomCoordinates(roomID, x, y, z)
-- 根据位置获取房间列表
roomTable = getRoomsByPosition(areaID, x,y,z)
-- 设置房间额外数据, 如长描述
setRoomUserData(roomID, key, value)
-- 在指定出口增加门
setDoor(roomID, exitCommand, doorStatus)

更多可能会用到的函数见前面的函数列表~

系统默认支持以下出口,其它出口只能增加为特殊出口

exitmap = {
  n = 1,
  north = 1,
  ne = 2,
  northeast = 2,
  nw = 3,
  northwest = 3,
  e = 4,
  east = 4,
  w = 5,
  west = 5,
  s = 6,
  south = 6,
  se = 7,
  southeast = 7,
  sw = 8,
  southwest = 8,
  u = 9,
  up = 9,
  d = 10,
  down = 10,
  ["in"] = 11,
  out = 12,
  [1] = "north",
  [2] = "northeast",
  [3] = "northwest",
  [4] = "east",
  [5] = "west",
  [6] = "south",
  [7] = "southeast",
  [8] = "southwest",
  [9] = "up",
  [10] = "down",
  [11] = "in",
  [12] = "out",
}

需要说明的是lock相关指令lockExitlockRoomlockSpecialExit并不是游戏意义上的锁,而是地图路径上的锁,快速行走不经过这里。如果要游戏意义上的锁需要用setDoor给指定方向的门增加上锁状态,快速行走会正常经过并自动使用unlock指令。

使用generic_mapper

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

京ICP备13031296号-4