Difference between revisions of "Mapping script"

Latest revision as of 20:46, 1 February 2023

Redirect to:

Manual:Mapper

@@ Line 1: / Line 1: @@
-Mudlet's mapper is split into two parts for the best compatibility on all MUDs - the display and functions in Mudlet, and a per-MUD Lua script that tracks where you are, allows mapping and provides aliases for using the mapper.
+#redirect [[Manual:Mapper]]
-= Existing mapping scripts =
-Pre-made mapping scripts are available from [http://forums.mudlet.org/search.php?keywords=mapping+script&terms=all&author=&sc=1&sf=titleonly&sr=topics&sk=t&sd=d&st=0&ch=400&t=0&submit=Search Mudlet forums] - all topics that have the '''(mapping script)''' prefix on them.
-= Making your own mapping script =
-If you'd like to code your own mapping script, see the [[Manual:Lua_Functions#Mapper_Functions|Mapper API]] and read on for a short tutorial.
-To start off, create a new script that'll be included with your mapping script (can even place it into the script folder for your mapping script), and have it do:
-<syntaxhighlight lang="lua">
-mudlet = mudlet or {}; mudlet.mapper_script = true
-</syntaxhighlight>
-This'll let Mudlet know that a mapping script is installed, so it won't bother you or whoever else installs your script with a warning that one is necessary.
-Next, you want to hook into Mudlet's gotoRoom(id) function and the user clicking on a room in the visual map - for that, define your own ''doSpeedWalk()'' function. Mudlet will store the directions / special exits commands your script will need to take in the ''speedWalkDir'' table, and the room IDs you'll pass through in the ''speedWalkPath'' table:
-<syntaxhighlight lang="lua">
-function doSpeedWalk()
-  echo("Path we need to take: " .. table.concat(speedWalkDir, ", ") .. "\n")
-  echo("Rooms we'll pass through: " .. table.concat(speedWalkPath, ", ") .. "\n")
-end
-</syntaxhighlight>
-''speedWalkPath'' is especially useful for making sure you're still on the path. Most Mudlet mapping scripts keep track of how many rooms along the path they have visited so far and check upon arrival into a new room to make sure it's still on the path.
-That's it! (But see below if you want more.)
-From here, you'd want to build a walking script that'll send the commands to walk you along the path, along with aliases for the user to use - see the [[Manual:Lua_Functions#Mapper_Functions|Mapper API functions]] and [[Manual:Event_Engine#Mudlet-raised_events|Mudlet mapper events]].
-== Adding rooms ==
-To make your first room, do the following steps:
-* create an area with setAreaName(areaID, areaname). You can choose any areaID - if you'd like to use the IDs incrementally, see which is the latest from getAreaTable()
-* if you want the Mudlet mapper to generate roomIDs for you, get one with createRoomID(). This is an optional step
-* create your room with addRoom(roomID)
-* give the room coordinates with setRoomCoordinates(roomID, x, y, z). If you're just starting out, put it at 0,0,0 so the room is at the center of the map
-* assign your room to an area with setRoomArea(roomID, areaID)
-* and finally, call centerview(roomID) to make the map view refresh and show your new room!
-=== Labelling rooms ===
-Rooms have three attributes which you can show on the map:
-* an ID. You can't change it; the ID is shown in the room's box when you check "IDs" in the dialog below the map and you're zoomed in far enough.
-* a symbol, also displayed in the room's box. You set it with the [https://wiki.mudlet.org/w/Manual:Lua_Functions#setRoomChar ''setRoomChar''] Lua function, or via the map's context menu.
-* a name, typically sent via GMCP. You add it to the map with [https://wiki.mudlet.org/w/Manual:Lua_Functions#setRoomName ''setRoomName''].
-The room name can be displayed along with a room's box. Its position defaults to "centered below the room". It is not visible by default because many maps have rooms that are quite close to each other; showing the names by default would create an ugly visual mess.
-If you want to enable room names in your mapper, you need to
-* stagger rooms. Four or five units' distance instead of one works best if you want to show every label; less is OK if you only show labels when the user asks you to.
-* call ''setMapUserData("room.ui_showName","1")''. The existence of this entry controls whether the "Names" checkbox is shown next to "IDs", below the map. This value is zero if the user has unchecked the "Names" checkbox.
-* optionally call ''setMapUserData("room.ui_nameFont","FontName")'' to change the names' font. The default is the same monospaced font used for the room IDs and symbols.
-* call ''setRoomUserData(room_id, "room.ui_showName","1")'' to show a room's label. You might want to add an entry to the map's pop-up menu which toggles this.
-If the name is misplaced (collision with another room, label, or whatever), you can modify the room's "room.ui_nameOffset" attribute to move it around. The value of this attribute consists of two floating-point values, separated by a space, which offset the room's label (in units of the room box's size). You might want to bind functions that increase or decrease these values to keys like Shift-Control-Arrow and/or Control-Numpad-2468. A hotkey to toggle a room's label display from "on" to "off" and back (e.g. Control-Numpad-5?) is also a good idea.
-You also might default to staggering room names. One possible algorithm: '''if''' a new room's X coordinate, divided by your default room distance, is an odd number '''then''' position its label with an offset like "0 -1.6", which would place it above the room in question. The optimal value for the Y offset depends on the font.
-Changes are displayed only when the map is next redrawn.
-Font options are global. Overriding them for a single room can be be implemented if requested.
-== Working with the mapper API ==
-Whenever working with mapper API, keep in mind of the following things:
-* you'll want to call centerview after you do some modifications, to get to have the map render your new changes
-== Translating directions ==
-Several functions in the mapper API take and return #'s for directions - and to make it easier to work with them, you can define a table that maps directions to those numbers in a script with the following:
-<syntaxhighlight lang="lua">
-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",
-}
-</syntaxhighlight>
-Then, using exitmap[input], you'll get a direction number or a direction name. Here's an example that uses it to work out in which directions are the exit stubs available in room 6:
-<syntaxhighlight lang="lua">
-lua local stubs = getExitStubs(6)
-for i = 0, #stubs do print(exitmap[stubs[i]]) end
-</syntaxhighlight>
-= More complex speedwalking and pathfinding =
-If you'd like to use a custom pathfinding algorithm instead of the built-in one, as of Mudlet 4.10 you can do that:
-* Set ''mudlet.custom_speedwalk = true''.
-* Your ''doSpeedwalk'' script will now see different parameters:
-<syntaxhighlight lang="lua">
-function doSpeedWalk()
-  echo("Room we're coming from: " .. speedWalkFrom .. "\n")
-  echo("Room you're going to: " .. speedWalkTo .. "\n")
-end
-</syntaxhighlight>
-The forum topic [https://forums.mudlet.org/viewtopic.php?f=6&t=22930&p=45930#p45930 Wayfinder] contains an example package that implements a shortest-path-first algorithm.
-= More complex room name search function =
-Sometimes the mapper script is not flexible enought to find the room name in your favorite game. From Mudlet 4.11 you can create a custom function that handle that search instead of the standard one included in the mapper
-* Type in the input area ''map config custom_name_search true'' to enable the usage of the custom function.
-* Write your own function called ''mudlet.custom_name_search''. The script call it for your:
-<syntaxhighlight lang="lua">
-mudlet.custom_name_search = function (lines)
-    ...
-        local line_count = #lines + 1
-        if string.match(cur_line, "   ") then
-          line_count = line_count - 1
-          room_name = lines[line_count]
-          -- map.echo("Name Search: room_nameome:" ..room_name)
-        elseif string.find(cur_line,prompt_pattern) then
-    ....
-    return room_name
-end
-</syntaxhighlight>
-I suggest to start from original name_search function in generic_mapper to avoid common problem.
-=Draw area exit names=
-When a room connect to another area's room, draw the exit area name on the line end.
-*To not show area names in a room
-<syntaxhighlight lang="lua">
--- don't show exit:
-setRoomUserData(roomid, "room.ui_dontShowAreaExitName", "yes")
-</syntaxhighlight>
-*To move normal exit name a little bit
-<syntaxhighlight lang="lua">
--- move normal exit a little bit
-setRoomUserData(roomid, "room.ui_areaExitNameOffset.south", "20")
-setRoomUserData(roomid, "room.ui_areaExitNameOffset.south", "20 20")
-</syntaxhighlight>
-*To move special exit a little bit
-<syntaxhighlight lang="lua">
--- move special exit a little bit
-setRoomUserData(roomid, "room.ui_areaExitNameOffset.northdown", "20")
-setRoomUserData(roomid, "room.ui_areaExitNameOffset.northup", "20 20")
-</syntaxhighlight>
-[[Category:Mudlet Manual]]

Difference between revisions of "Mapping script"

Latest revision as of 20:46, 1 February 2023

Navigation menu

Search