Manual:Mapper

Mapper

Maps and Autowalking

Maps are implemented as directed graphs of connected nodes (rooms). Nodes are connected by edges (exits). Nodes are referenced by unique integer IDs. Edges fall into 2 categories: Standard exits with a visual representation on the map (e. g. north, south) and "special exits" without a calculated visual representation on the map e. g. the command "jump cliff" is a special exit that connects to a room without a clear spatial orientation. However, special exits can be visually represented if the user provides custom exit line strips. Standard exits are referenced by their respective node and a directional integer value. Special exits are referenced by their respective nodes and strings that hold the exit commands. Both nodes and individual exits can seperately be locked and thus excluded from speed walk path finding graphs. Path finding uses the fast A* search algorithm. Mudlet choses a path with the fastest travel time (-> room weights) as opposed to the shortest path.

Maps are divided into areas or zones where the area/room relationship is unique, i. e. rooms cannot be in more than 1 area.

Note: Areas help make do with the typical geographical irregularities of MUD maps where an entire city with hundrets of rooms makes up a single room on a wilderness map. In other words, if you can't make a place look geographically correctly, create (sub) areas to deal with the problem.

There are 2 forms of visual representations of maps. Standard mode shows exits and custom exit lines whereas "grid mode" hides exit details and sizes rooms to form a perfect grid without any empty space in between rooms. Grid maps can be made to look exactly like ASCII color text maps with character symbols to keep the look and feel of the MUD. Technically, grid maps are a special optimized representation of the typically very large LPC MUD style wilderness maps where every room has 8 direct neighbors in a n*m grid of rooms with relatively few holes. The grid map implementation uses pre image caching and fast gfx hardware render support and can thus render very large grid maps in less than 1ms that would take much longer if the map were to be displayed in regular mode. Changing the zoom level of maps in grid mode can take a significant amount of time if the maps are very large, because the pre cached images of the map need to be recreated at the new zoom level. Areas remember their particular zoom level so this is no hindering issue in actual gameplay.

Any map can be displayed in both modes, but the visual map editor only works in regular mode. Consequently, grid map mode need to be turned off before editing the map. Grid mode is an area property.

regular mode grid mode grid mode.

Areas

Areas are defined by a unique integer number ID and a unique area name. Mudlet builds an internal numerical area ID table on the basis of the rooms that belong to the respective areas. Mudlet keeps a seperate lookup table to retrieve the area name on the basis of the area IDs. This name lookup table is not guaranteed to be correct because it may be imported invalid information if the map has been downloaded by the game server as an xml map description file on the basis of the MMP protocol. However, if the map has been created with Mudlet directly, there will be no such problems as the area name lookup table API is made to enforce uniqueness.

Area Properties

• area map display mode (-> regular map display mode or grid mode)
• area name

Rooms

Rooms are invisible on the map unless the required properties have been set.

Room Properties

• Room object need following required properties in order to be shown on the respective area map:
  • unique room ID in form of an integer value
  • area ID in form of an integer value (To which area does this room belong - or in other words, which area map displays this room)
  • x, y and z coordinates as integer values which relate to its paricular area map coordinate system

• Optional room properties:
  • regular exits with or without respective exit locks
  • special exits with or without respecitve special exit locks
  • room lock
  • exit stubs (draw exit directions even though the exit rooms have not yet been defined)
  • custom exit lines (user defined line strips of various formats to visualize special exits or redefine regular exit lines)
  • searchable room name that can be used for bookmarks, annotations etc.
  • room weight (How long does it travel through this node. A high room weight makes it less likely that this room will be chosen for pathfinding e. g. a safe road should have a low weight, whereas a dangerous place should have a high weight
  • room color
  • room character e. g. the symbol $ to symbolize a bank or H for a hotel.

Advanced Map Features

Map Labels

Maps can be embellised with images and text labels. Map labels can be either used as background (default) or as the top most foreground e. g. for player name location scripts. Labels are defined by position and size according to the map coordinate system and keep their position and size relative to the rest of the map when the map is zoomed or moved. Contrary to rooms which work on the basis of integer (natural numbers) coordinates, labels are described (with respect to both position & size) by real numbers in order to allow for more advanced placement and label sizes within the map coordinate system. Map labels are stored in form of png images directly in the map file and are thus a direct part of the map. As these images are being scaled to fit the label creation size, the image quality will depend on the initial size of the label (the large the better the quality, but the more memory will be used).

(The desert and dragon images used in this example are licensed under the Creative Commons Attribution 2.0 Generic license and can be found here: http://en.wikipedia.org/wiki/File:Ninedragonwallpic1.jpg and http://en.wikipedia.org/wiki/File:Siwa_sand_dunes2009a.jpg)

Custom Exit Line Definitions

The mapper supports user defined visual exit lines on the basis of a sequence of line points in the map coordinate system. Custom lines as well as labels work on real numbers to allow for fine grained placement. User defined lines can be solid, dotted, dashed etc. line types with or without ending arrows. The line color can be freely selected. By default the regular exit color is being used.

The above example shows 3 different types of user defined exit lines, where the orange one on the left has been selected by the user in order to be edited.

Custom exit lines are purely visual tools and have no effect on the pathfinding, but each custom line must be linked to a valid room exit - either standard or special exit.

Visual Map Editor

Maps can be comfortably edited by using the visual map editor or by scripts. The editor behaves like the usual WYSIWYG editors. Select objects with a left click and then right click to open a context menus and do actions on the selected objects.

Object selection

• left click = select element
• left click + drag = sizing group selection box choosing all rooms in the box on the current z-level
• left click + shift + drag = sizing group selection box choosing all rooms in the box on all z-levels
• left click + alt (or the mapper menu move map buttons) = move map
• left click + control = add a room to current group selection or remove it

if multiple rooms are being selected a room id selection list box is being shown where you can fine tune the current room selection via the usual left click + control or left click + shift. The box disappears if the number of rooms in group selection is zero.

Moving Objects

Move selected objects either by right click and select "move" or with following handy short cut:

• left button down on custom line point + drag = move custom line point
• left button down + drag usually moves the item directly (as a handy shortcut) if only one element has been selected
• or hold left button down + control + drag if multiple rooms have been selected

Mapping Special Cases

This is a quick guide on ways to handle special movement scenarios.

Exit Scripts

Some of the following scripts depend on this functionality. This serves to execute a script if a given exit is sent. For instance in the speedwalk function, every direction before being sent can call this function.

function checkExitScript(room, dir)
        --room is the room id #, dir is the direction we are attempting
	local exitScript = getRoomUserData(room, "exitScript"..dir)
	if exitScript ~= "" then
		assert(loadstring(exitScript)) ()
	end
end

Delayed Movements

This approach can be used for things such as waiting for a ship to arrive. It depends on the exitScript function above being defined.

Alias: ^pauseUntil "(.+)" (.+)$

Usage: pauseUntil "board ship" A ship sails into port.$

Script:

setRoomUserData(roomid, "exitScript"..matches[2], "moveStop=1;tempTrigger("..matches[3]..", [[moveStop=nil;speedWalkPath = roomsToWalk;doSpeedWalk()]],true)")

The moveStop=1 causes my speedwalker to stall, the tempTrigger part triggers the action to continue walking. When a message such as "A ship sails into port" on which the direction "board ship" will be launched. Similarly the exit "disembark ship" will pause the mapper until the message indicating we've landed has been seen. Note that because we check the exitScripts BEFORE moving a direction this allows us to wait.

Non-Standard Room Entrances

Sometimes we move in non-standard ways, such as teleportation that might not give a standard room description to trigger a movement off. However there is usually other information.

Alias: ^automove "(.+)" .+$

Usage: automove "enter chamber" You try to enter the chamber, but a trap door opens, sending you spiraling into darkness!

This once again makes use of the exitScript function, script:

setRoomUserData(roomid, "exitScript"..matches[2], "tempTrigger("..matches[3]..", [[onFollow(nil)]],true)")

onFollow() is another function I have which monitors the queue of directions to move. How I setup this function, nil means attempt to move from the current room to the next room id.

Mapping Temporary Areas

This is rather easy, simply set a variable, let's call it "tempRoom" and in your room creation code, set a piece of UserData to that value. Then use an alias to search through the UserData for rooms with that flag and delete them. This is useful for dynamic areas that change such as ones that are randomly generated on a mud reboot.

Mapper tips

Placing the mapper into a corner

Here's a snippet you can use to place the mapper window into a corner and have it automatically come up whenever you open Mudlet. To use this, create a new script (you can make it anywhere) and copy/paste the code into it.

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

Mapper Favorites

This post here describes how to add a right click menu to your mapper filled with rooms to speedwalk to.