Generic mapper package

Game	non-mud specific
By	Mudlet Community
Download	none, included in Mudlet (source code available here)
Dependencies	Mudlet 4.17 for full command availability

Description

This script allows for semi-automatic mapping using the included triggers. While different games can have dramatically different ways of displaying information, some effort has been put into giving the script a wide range of potential patterns to look for, so that it can work with minimal effort in many cases. The script locates the room name by searching up from the detected exits line until a prompt is found or it runs out of text to search, clearing saved text each time a prompt is detected or a movement command is sent, with the room name being set to the last line of text found. An accurate prompt pattern is necessary for this to work well, and sometimes other text can end up being shown between the prompt and the room name, or on the same line as the room name, which can be handled by providing appropriate patterns telling the script to ignore that text. Below is an overview of the included commands and important events that this script uses to work. Additional information on each command or event is available in individual help files.

Usage

Type map basics or map help in game to get started.

See also: Mudlet Forums

Commands

Map Save

map save

This command creates a copy of the current map and stores it in the profile folder as map.dat. This can be useful for creating a backup before adding new content, in case of problems, and as a way to share an entire map at once.

Map Load

map load <optional download address>

This command replaces the current map with the map stored as map.dat in the profile folder. Alternatively, if a download address is provided, a map is downloaded from that location and loaded to replace the current map. If no filename is given with the download address, the script tries to download map.dat. If a filename is given it MUST end with .dat.

Map Show

map show

This command shows a map window, as specified by the window configs set via the map window command. It isn't necessary to use this method to show a map window to use this script, any map window will work.

Map Export

map export <area name>

This command creates a file containing all the informatino about the named area and stores it in the profile folder, with a file name based on the area name. This file can then be imported, allowing for easy sharing of single map areas. The file name will be the name of the area in all lower case, with spaces replaced with underscores, and a .dat file extension.

Map Import

map import <area name>

This command imports a file from the profile folder with a name matching the name of the file, and uses it to create an area on the map. The area name used can be capitalized or not, and may have either spaces or underscores between words. The actual area name is stored within the file, and is not set by the area name used in this command.

Start Mapping

start mapping [area name]

This command instructs the script to add new content to the map when it is seen. When first used, an area name is mandatory, so that an area is created for new rooms to be placed in. If used with an area name while the map shows the character within a room on the map, that room will be moved to be in the named area, if it is not already in it. If used without an area name, the room is not moved, and mapping begins in the area the character is currently located in.

Stop Mapping

stop mapping

This command instructs the script to stop adding new content until mapping is resumed at a later time. The map will continue to perform other functions.

Find Prompt

find prompt

This command instructs the script to begin searching newly arriving text for something that matches one of its known prompt patterns. If one is found, that pattern will be set as the current prompt pattern. This should typically be the first command used to set up this script with a new profile. If your prompt appears after using this command, but there is no message saying that the prompt has been found, it will be necessary to use the map prompt command to manually set a pattern.

Map Prompt

map prompt <prompt pattern>

This command manually sets a prompt pattern for the script to use. Because of the way this script works, the prompt pattern should match the entire prompt, so that if the text matching the pattern were removed, the line with the prompt would be blank. The patterns must be of the type used by the Lua string library. If you are unsure about what pattern to use, seek assistance on the Mudlet Forums or the Mudlet Discord channel.

Map Debug

map debug

This command toggles the map script's debug mode on or off when it is used. Debug mode provides some extra messages to help with setting up the script and identifying problems to help with troubleshooting. If you are getting assistance with setting up this script, using debug mode may make the process faster and easier.

Map Ignore

map ignore <ignore pattern>

This command adds the given pattern to a list the script maintains to help it locate the room name. Any text that might appear after a command is sent to move and before the room name appears, or after the prompt and before the room name if several movement commands are sent at once, should have an ignore pattern added for it.

If the given pattern is already in the list of ignore patterns, that pattern will be removed from the list.

Example:

map ignore ^You are hungry%.$

to match exactly one line

map ignore ^The clock strikes %d+%.$

to match a number

map ignore ^You walk %a+%.$

to match a word, e.g. east

Move Method

map movemethod <movement word>

This command will add a movement method for the script to look for when moving between rooms. If your game has methods such as "walk north", "swim south" or similar, add "walk" or "swim" as necessary. For single room movement only.

If the given method is already in the list of movement methods, that method will be removed from the list.

Map Areas

map areas

This command displays a linked list of all areas in the map. When clicked, the rooms in the selected area will be displayed, as if the map rooms command had been used with that area as an argument.

Map Rooms

map rooms <area name>

This command shows a list of all rooms in the area, with the roomID and the room name, as well as a count of how many rooms are in the area total. Note that the area name argument is not case sensitive.

Set Area

set area <area name>

This command move the current room into the named area, creating the area if needed.

Map Mode

map mode <lazy, simple, normal, or complex>

This command changes the current mapping mode, which determines what happens when new rooms are added to the map.

• In lazy mode, connecting exits aren't checked and a room is only added if there isn't an adjacent room with the same name.

• In simple mode, if an adjacent room has an exit stub pointing toward the newly created room, and the new room has an exit in that direction, those stubs are connected in both directions.

• In normal mode (default), the newly created room is connected to the room you left from, so long as it has an exit leading in that direction.

• In complex mode, none of the exits of the newly connected room are connected automatically when it is created.

Add Door

add door <direction> [none|open|closed|locked] [yes|no]

This command places a door on the exit in the given direction, or removes it if "none" is given as the second argument. The door status is set as given by the second argument, default "closed". The third argument determines if the door is a one-way door, default "no".

Add Portal

add portal [-f] <entry command>

This command creates a special exit in the current room that is entered by using the given entry command. The given entry command is then sent, moving to the destination room. If the destination room matches an existing room, the special exit will link to that room, and if not a new room will be created. If the optional "-f" argument is given, a new room will be created for the destination regardless of if an existing room matches the room seen when arriving at the destination.

Shift

shift <direction>

This command moves the current room one step in the direction given, on the map.

Merge Rooms

merge rooms

This command combines all rooms that share the same coordinates and the same room name into a single room, with all of the exits preserved and combined.

Clear Moves

clear moves

This command clears the script's queue of movement commands, and is intended to be used after you attempt to move while mapping but the movement is prevented in some way that is not caught and handled by a trigger that raises the onMoveFail event.

Set Exit

set exit <direction> <destination roomID>

This command sets the exit in the current room in the given direction to connect to the target room, as specified by the roomID. This is a one-way connection.

Map Me

map me

This command forces the script to look at the currently captured room name and exits, and search for a potentially matching room, moving the map if applicable. Note that this command is generally never needed, as the script performs a similar search any time the room name and exits don't match expectations.

Map Path

map path <room name> [; area name]

This command tries to find a walking path from the current room to the named room. If an area name is given, only rooms within that area that is given are checked. Neither the room name nor the area name are case sensitive, but otherwise an exact match is required. Note that a semicolon is required between the room name and area name, if an area name is given, but spaces before or after the semicolon are optional.

Example:

map path main street ; newbie town

Map Character

map character <name>

This command tells the script what character is currently being used. Setting a character is optional, but recall locations and prompt patterns are stored by character name, so using this command allows for easy switching between different setups. The name given is stored in map.character. The name is a case sensitive exact match. The value of map.character is not saved between sessions, so this must be set again if needed each time the profile is opened.

Map Recall

map recall

This command tells the script that the current room is the recall point for the current character, as stored in map.character. This information is stored in map.save.recall[map.character], and is remembered between sessions.

Map Config

map config <setting> <optional value>

This command changes any of the available configurations listed below. If no value is given, and the setting is either 'on' or 'off', then the value is switched. When naming a setting, spaces can be used in place of underscores. Details of what options are available and what each one does are provided.

speedwalk_delay

when using the speedwalk function of the script, this is the amount of time the script waits after either sending a command or, if speedwalk_wait is set, after arriving in a new room, before the next command is sent. This may be any number 0 or higher.

speedwalk_wait

when using the speedwalk function of the script, this indicates if the script waits for your character to move into a new room before sending the next command. This may be true or false.

speedwalk_random

when using the speedwalk function of the script with a speedwalk_delay value, introduces a randomness to the wait time by adding some amount up to the speedwalk_delay value. This may be true or false.

stretch_map

when adding a new room that would overlap an existing room, if this is set the map will stretch out to prevent the overlap, with all rooms further in the direction moved getting pushed one further in that direction. This may be true or false.

max_search_distance

when mapping, this is the maximum number of rooms that the script will search in the movement direction for a matching room before deciding to create a new room. This may be false, or any positive whole number. This can also be set to 0, which is the same as setting it to false.

search_on_look

when this is set, using the "look" command causes the map to verify your position using the room name and exits seen following using the command. This may be true or false.

clear_lines_on_send

when this is set, any time a command is sent, any lines stored from the game used to search for the room name are cleared. This may be true or false.

mode

this is the default mapping mode on startup, and defines how new rooms are added to the map. May be "lazy", "simple", "normal" or "complex".

download_path

this is the path that updates are downloaded from. This may be any web address where the versions.lua and generic_mapper.xml files can be downloaded from.

prompt_test_patterns

this is a table of default patterns checked when using the "find prompt" command. The patterns in this table should start with a '^', and be written to be used with the Lua string library. Most importantly, '%' is used as the escape character instead of '\' as in trigger regex patterns.

custom_exits

this is a table of custom exit directions and their relevant extra pieces of info. Each entry should have the short direction as the keyword for a table containing first the long direction, then the long direction of the reverse of this direction, and then the x, y, and z change in map position corresponding to the movement. As an example: us = {'upsouth', 'downnorth', 0, -1, 1}

custom_name_search

when this is set, instead of running the default function name_search, a user-defined function called 'mudlet.custom_name_search' is used instead. This may be true or false.

use_translation

when this is set, the lang_dirs table is used to translate movement and status commands in some other language into the English used by the script. This may be true or false.

debug

when this is set, the script will start in debug mode. This may be true or false.

Map Window

map window <setting> <value>

This command changes any of the available configurations listed below, which determine the appearance and positioning of the map window when the 'map show' command is used. Details of what options are available and what each one does are provided.

x

this is the x position of the map window, and should be a positive number of pixels or a percentage of the screen width.

y

this is the y position of the map window, and should be a positive number of pixels or a percentage of the screen height.

w

this is the width of the map window, and should be a positive number of pixels or a percentage of the screen width.

h

this is the height of the map window, and should be a positive number of pixels or a percentage of the screen height.

origin

this is the corner from which the window position is measured, and may be 'topright', 'topleft', 'bottomright', or 'bottomleft'.

shown

this determines if the map window is shown immediately upon connecting to the game. This may be true or false. If you intend to have some other script control the map window, this should be set to false.

Map Translate

map translate <english direction> <translated long direction> <translated short direction>

This command sets direction translations for the script to use, either for commands entered to move around, or listed exits the game shows when you enter a room. Available directions: north, south, east, west, northwest, northeast, southwest, southeast, up, down, in, and out. Also you can customize special commands sent to mud like 'look'.

Map Basics (quick start guide)

Mudlet Mapper works in tandem with a script, and this generic mapper script needs to know 2 things to work: - <dim_grey>room name</syntaxhighlight> $ROOM_NAME_STATUS ($ROOM_NAME) - <dim_grey>exits</syntaxhighlight> $ROOM_EXITS_STATUS ($ROOM_EXITS)

1. <link: start mapping>start mapping <optional area name></link> If both room name and exits are good, you can start mapping! Give it the area name you're currently in, usually optional but required for the first one. 2. <link: find prompt>find prompt</link> Room name or exits aren't recognised? Try this command then. It will make the script start looking for a prompt using several standard prompt patterns. If a prompt is found, you will be notified, if not, you will need to set a prompt pattern yourself using <link: prompt>map prompt</link>. Reach out to the <urllink: https://discord.gg/kuYvMQ9>Mudlet community</urllink> for help, we'd be happy to help you figure it out! 3. <link: debug>map debug</link> This toggles debug mode. When on, messages will be displayed showing what information is captured and a few additional error messages that can help with getting the script fully compatible with your game. 4. <link: 1>map help</link> This will bring up a more detailed help file, starting with the available help topics.

Room Find

room find <room name>

rf <room name>

This command will search all rooms and return a list of matches.

Room Look

room look [roomID]

rl [roomID]

This command will display detailed information about the current room. Optionally a roomID can be provided.

Showpath

showpath <roomID>

showpath <fromID> <toID>

This command displays a path from your current room to the roomID specified. If two roomID's are specifed it will display a path from a remote room to another room.

Special Exits List

spe list [filter]

This command displays a list of all known special exits. You can alternatively provide an optional filter to return a list containing those words.

Example:

spe list worm warp

Feature List

feature list

This command displays a list of all map features created via feature create and the associated room characters.

Area Add

area add <area name>

This command will create a new area and automatically give it an ID.

Example:

area add My City

create a new area called My City

Area Delete

area delete <area name>

This command will delete the given area. If the area is really big (thousands of rooms), deleting it at once would take a really long while and freeze your Mudlet while doing so. To combat the unpleasant experience, the script breaks up area deletion into batches of rooms (100 by default). While this still heavily impacts Mudlets performance, it allows you to see a progress meter of how far it has gotten and gives you an ability to pause it at any time by doing 'cancel area deletion'.

Example:

area delete My City

delete an area called My City

Cancel Area Deletion

cancel area deletion

This comand will stop an area deletion that has started. This will NOT restore deleted rooms - it merely pauses the process, so you can resume it with 'area delete' later on. You can type this in while Mudlet is deleting an area - it'll take a short while for letters to show up, but they will eventually.

Area Rename

area rename <name>

This command will rename the current area you're in to the new name.

Example:

area rename My City

call the area you're in My City from now on

Arealock

arealock [filter]

This command displays a list of areas you can lock/unlock, you can also give it an area name to filter by. If an area is locked the mapper will not attempt to speedwalk or go through any of the rooms in the area.

Example:

arealock City

Room Coordinates

room coords [v<roomID>] <x> <y> <z>

rc [v<roomID>] <x> <y> <z>

This command will move a room to the new map coordinates. x,y and z will specify the new location of the room. The room ID is optional, it'll move the current room if you don't provide one.

Example:

rc nw

move the room to be nw of the current location

rc v34 w

move the room ID 34 west, note the letter 'v' in the command

rc 1 -5 10

move the current room to those exact coordinates

rc v12 8 3 -8

move the room #12 to 8x, 3y and -8z

rc 14x 5y

move the current room to be at 14x and 5y, but the same z-level you're on. You can include all three of x, y, z coordinates or only one as you wish

Room Delete

room delete <direction|roomID>

rld <direction|roomID>

This command will delete a room given a relative direction or roomID.

Example:

rld

current room, will delete the room you're currently in

rld n

relative direction, will delete the room that's north of you

rld 513

using roomID, will delete the room with ID 513

Room Weight

room weight [direction|roomID] <weight>

rw [direction|roomID] <weight>

This command updates the weight of a room, making it more or less desirable to travel through. Direction or roomID is optional and defaults to the current room.

Example:

rw 10

will set the room weight of the room you're standing in to 10

rw n 4

relative direction, will set the room weight of the room that's to the north of you to four

rw 2343 2

using roomID, will set the room weight of room 2343 to 2

Room Weight Exit

rwe [roomID] <weight> <exit>

This command updates the weight of a room exit, where weight is a positive number (default for exits is 0). Setting a higher weight will make the exit be less likely to be used. The exit can be a cardinal direction of either n,e,s,w,ne,se,sw,ne,up,down,in,out or the exact special exit text (including the script: part). This alias sets a weight one way only, so if you want to set it both ways, use it on the opposite side as well. Use 'rl' to check exit weights.

Example:

rwe 1 n

will set the weight of the exit north to 1

rwe 2434 0 e

will reset the exit weight of an east exit that leads out from the 2434 room

Room Link

room link [roomID] <direction> [one]

rlk [roomID] <direction> [one]

This command will link a room given a direction and optional roomID. You can also add 'one' at the end of the command to make it be a one-way link.

Example:

rlk n

relative direction, will link if exists a room to the north of this one to your current location

rlk 351 n

exact roomID and direction, will link the current room to room #351 via a north exit

rlk n one

will make an exit north one-way

Room Unlink

room unlink <direction>

urlk <direction>

Unlink a room given a direction. This function will unlink exits both ways, or one way if there is no incoming exit.

Example:

urlk nw

relative direction, will unlink to the northwest, and from the northwest room to the southeast

Room Door

rd [roomID] <direction> <open|closed|locked|clear>

Will create a door from the current room to a direction specified. Door status can be open or o, closed or c, locked or l, clear or gone. To delete a room, use clear or gone. Setting doors is one-way - to set two-way doors, use the alias from the opposite direction.

Example:

rd n

add a one-way door north from the current room

rd 23 w closed

add a closed door leading west in room 23

rd n clear

remove the door to the north from the current room on this side only

Room Character

rcc <character|clear> [roomID]

This command will assign a single character, letter or number to the current room, or an optional given room. Using clear will remove any characters.

Example:

rcc $

put the dollar sign in the current room (e.g. to indicate a shop or bank)

rcc C 234

put the letter C onto room 234

rcc clear

remove any letter from the current room

Special Exits

exit special <direction|roomID> <command>

spe <direction|roomID> <command>

This command will link two rooms via custom or special exit/script.

Example:

spe n push rock

relative direction, will go to the room that's north of you by doing 'push rock'

spe 125 pull lever

will go to room 125 from the current one by pulling a lever

You can also specify a script to do code for you, by starting the exit command with script.

Example:

spe 125 script: sendAll("pull lever", "enter gate")

Remote Special Exits

spev <fromID> <toID> <command>

This command will add a special exit between two remote rooms.

Example:

spe 125 560 push rock

will link room 125 to room 560 with the command 'push rock'

Clear Special Exits

exit special clear <direction|roomID>

spe clear <direction|roomID>

This command will clear all special exits from the current, relative or given roomID.

Example:

spe clear

delete all special exits in the room you're currently in

spe clear n

delete all special exits in the room that's north of you

spe clear 513

delete all special exits in room #513

Room Area

room area [v<roomID>] <area name|areaID>

This command moves the current room to another area or a given optional room.

Example:

room area My New Area

move the room you're in to 'My New Area'.

room area v123 My New Area

move room 123 to My New Area

room area 44

move the current room to the area ID 44

Room Label

room label [roomID] [fgColor] [bgColor] <message>

This command adds a label to the current or specified room. Foreground and background color are optional.

Example:

room label My Label

adds a 'My Label' label to the current room

room label 342 My Label

adds a label to room #342

room label green My Label

adds a green label with a transparent background to the current room

room label green black My Label

adds a label with a green foreground and black background to the current room

room label 34 green black My Label

adds a label with a green foreground and black background to room #34

Area Labels

area labels <area name>

This command displays all labels in a given area, with a link to delete.

Example:

area label My Area

Feature Create

feature create <feature> [char <room character>]

This command will create a new map feature for use on rooms. You can also optionally add a character mark to the feature, which will be set when a map feature is added to a room. Note: Map feature names are not allowed to contain numbers.

Example:

feature create A Nexus Point char N

creates a new feature 'A Nexus Point' with an assigned room character 'N'

Room Create Feature

room create feature [v<room id>] <feature>

rcf [v<room id>] <feature>

This command will add a created map feature to the room. If the map feature is associated with a character mark, it will be set on the room and existing marks get overwritten. The room number to add the feature to can be given with the optional argument (note: there is no space between the v and the ID).

Example:

rcf A Nexus Point

add the feature 'A Nexus Point' to the current room

rcf v123 A Nexus Point

add the feature 'A Nexus Point' to room #123

Room Delete Feature

room delete feature [v<room id>] <feature>

rdf [v<room id>] <feature>

This command removes a map feature from the room. If the map feature is associated with a character mark and its set on the room, a random character mark from the other map features on the room is chosen to replace it. The room number to delete the feature from can be given with the optional argument (note: there is no space between the v and the ID).

Example:

rdf v123 A Nexus Point

removes the feature 'A Nexus Point' from the room #123

Feature Delete

feature delete <feature>

This command deletes a global map feature and removes it from all rooms.

Example:

feature delete A Nexus Point

removes the global feature 'A Nexus Point' and removes it from all rooms

Events

onNewRoom Event

This event is raised to inform the script that a room has been detected. When raised, a string containing the exits from the detected room should be passed as a second argument to the raiseEvent function, unless those exits have previously been stored in map.prompt.exits.

onMoveFail Event

This event is raised to inform the script that a move was attempted but the character was unable to move in the given direction, causing that movement command to be removed from the script's movement queue.

onForcedMove Event

This event is raised to inform the script that the character moved in a specified direction without a command being entered. When raised, a string containing the movement direction must be passed as a second argument to the raiseEvent function.

The most common reason for this event to be raised is when a character is following someone else.

onRandomMove Event

This event is raised to inform the script that the character has moved in an unknown direction. The script will compare the next room seen with rooms that are adjacent to the current room to try to determine the best match for where the character has gone.

In some situations, multiple options are equally viable, so mistakes may result. The script will automatically keep verifying positioning with each step, and automatically correct the shown location on the map when possible.

onVisionFail Event

This event is raised to inform the script that some or all of the room information was not able to be gathered, but the character still successfully moved between rooms in the intended direction.

onPrompt Event

This event can be raised when using a non-conventional setup to trigger waiting messages from the script to be displayed. Additionally, if map.prompt.exits exists and isn't simply an empty string, raising this event will cause the onNewRoom event to be raised as well. This functionality is intended to allow people who have used the older version of this script to use this script instead, without having to modify the triggers they created for it.

Examples

Prompt Pattern Matching

Pattern matching (used with map prompt and also map ignore commands) uses Lua pattern matching (as opposed to regex matching used in Aliases or Triggers). While similar there are a few key differences, notably the use of percentage character (%).

Character Classes

.	all characters
%a	letters
%c	control characters
%d	digits
%l	lower case letters
%p	punctuation characters
%s	space characters
%u	upper case letters
%w	alphanumeric characters
%x	hexadecimal digits
%z	the character with representation 0

Modifiers

+	1 or more repetitions, as many times as possible
*	0 or more repetitions, as many times as possible
-	also 0 or more repetitions, as few times as possible
?	optional (0 or 1 occurrence)

Therefore to match a basic prompt such as;

<123hp 456mana 789moves>

we would use this pattern

<%d+hp %d+mana %d+moves>

You can use a percentage character (%) to escape (ignore) certain special characters. Special characters in Lua patterns are ( ) . % + - * ? [ ^ $

Hp: 123(200) Mp: 456(500) Mv: 789(1000) Xp: 54321
Hp: %d+%(%d+%) Mp: %d+%(%d+%) Mv: %d+%(%d+%) Xp: %d+$

Note: Watch for spaces at the end of your prompt, they can trick you up.

Note: ^ and $ can be used to match a start of a line, and the end of a line.

Note: You can test your patterns on the command line. It will return matching patterns or nothing if no match is found.

lua string.match(aString, pattern)
lua string.match("50%", "%d+%%")

More examples;

103/103HP | 113/121STA | 105/105ST | 115/115FO | Abid, late at night >
%d+/%d+HP | %d+/%d+STA | %d+/%d+ST | %d+/%d+FO | .+ >

Helpful Additions

Generic Mapper Additions