IRE mapping script

This is the Lua component to make the Mudlet Mapper work for IRE games and StickMUD. You'll need to import the xml below in order for autowalking to work on Achaea, Aetolia, Lusternia, Imperian, or Starmourn. The script is included in the standard StickMUD GUI. See the download section to get started!

It has many features such as:

• automatic repathing if you get off course
• locking of whole areas
• auto-swimming
• mapping
• scriptable exits
• using special movement types for even faster speedwalking (like gallop, glide, dash, sprint, runaway, and more)
• configurable teleportation methods
• maintaining map features and finding the shortest route to the nearest one of a given type (like: goto junk, goto repair, goto harbour, ...)

The script is written by Vadi, maintained by a group of volunteers. Have feedback, comment or a suggestion? Please comment here or join the Discord! Maintenance of the crowdmaps is mostly done by the following individuals: Qwindor (Achaea and Starmourn), Cylon (Lusternia) and Tamarindo (StickMUD).

To contact Qwindor about adjustments that need to be made to the Achaean crowdmap you can contact him in game or on skype at "qwindor.rousseau". Please include room numbers if possible to make it easier and faster for the corrections to be made.

To contact Cylon regarding the Lusternia crowdmap you can reach him in game as Kaiel or on Discord, @Cylon#2741

The script is open-source and includes contributions from Kard, Keneanung, Patrick, Qwindor, Wyd and others! Would you like to add something? Get in touch with Vadi for more.

Would you like to setup a crowdmap for your game? Check out this template repo to get started.

Are you a game admin who'd like to add your game to the script? If you have similar GMCP room data, that is certainly possible.

Download

latest version (right-click and 'Save as'), see the changelog here.

To upgrade your mapper script (not map): click on Package Manager or Toolbox → Package manager, select Install, and point it to the new mudlet-mapper.xml that you downloaded from above. It's best to reconnect or restart Mudlet after you to do, because the script won't know what game you're playing until it sees the welcome screen.

The mapper script is absolutely free, though if you'll be making adjustments to it, please contribute them back!

Installing

• make sure you're using a version of Mudlet that has a mapper (either a Map button or a Toolbox → Show Map option)
• import this script either as a package or a module in Mudlet
• restart Mudlet
• if you're on Achaea, Starmourn, Lusternia or StickMUD do mconfig crowdmap on
• if you can use wormholes, do mconfig lockwormholes off - if you can't use wormholes, do mconfig lockwormholes on. Type mconfig to see all available options!
• done!

Updating

The mapper script gained a feature a while ago where it is able to let you know when there's a new version of the script available, and even download it for you. You can update using that - or you can come back to this page, download the latest copy and install that.

Updating the map

in Achaea, Starmourn, Lusternia or StickMUD

Make sure you have mconfig crowdmap on. To force an update on the map, type rl and then click on (force) besides Check for all updates. This will redownload the map for you - make sure you have the map window open, loading the new map won't work otherwise.

other IRE games and StickMUD

To update your map, make sure that the map is open, and then go to Settings → Special Settings, and click on the Download map button. Your map will be downloaded straight from the game as it provides it to you.

If any find any mistakes in the map, BUG them, if you are using the game-provided map.

Support

If you wish to leave any feedback on the script, please comment on the Mudlet forums!

Should the crowdmap say locked/unlocked 0 wormholes using crowdmap?

If you're using the crowdmap, it should not. The crowdmap format was accidentally updated to a version that requires a newer Mudlet to load it - please update your Mudlet to continue using it.

How to stop using sewer shortcuts?

Do mconfig locksewers on to stop the mapper from using any sewer grates. If you'd only want it to stop sewers from a particular city, do arealock sewers and lock that specific area beneath the city.

To allow it to use sewer exits again, do mconfig locksewers off.

How to use wormholes?

If your map has wormholes mapped, then doing mconfig lockwormholes off will enable the mapper to use them.

Note that wormholes are only available by default in the Achaea crowdmap - the IRE-provided maps lack wormhole data.

How to make it use wings in Achaea?

This is a new feature of the mapper for Achaea so you need to update this mapper script to make sure it's at least version 12.8.1+ and your map as well (mconfig crowdmap needs to be on - not the map from the Mudlet special settings). To enable Atavian wings, do mconfig duanatharan on, or to enable Eagle wings, do mconfig duanathar on. That's it!

When Atavian wings are enabled, the mapper will make use of both duanathar and duanatharan, so you don't need to enable duanathar as well. The mapper is smart and won't use the wings if you're inside, only use wings if that is a quicker path and not use wings if you're off the Prime continent. If you start off walking when you're inside and you get outside, the mapper will use wings as well if they're quicker to your destination than walking.

How can I make it not remove my wings?

You can do mconfig removewings off. This is on by default, to prevent you from being forced to go up to clouds where you'll get ganked - the mapper instead only wears and removes them when you're going to clouds yourself.

How can I say the keyword in another language?

You can set it with mconfig winglanguage <language or none> - for example, mconfig winglanguage mhaldorian.

Possible problems

The wings feature involves a fair bit of different components. If your wings aren't being used as they should be, here are some things to look at:

• is GMCP on? Check the General tab of Mudlet settings. If you don't even see the option, update your Mudlet. If it's there but it's not on, enable it, and reconnect.
• are you using the crowdmap? Do mconfig crowdmap on to enable it - it'll check for map updates then and download the crowdmap. This is also necessary for the next step...
• is the crowdmap working? If it says it (un)locked 0 wormholes when it downloads, then it's not working quite properly. The map crowdmap format was accidentally updated to a newer one, which means you need to update your Mudlet to a newer one.
• is the area you are in marked as being on the Prime continent? Because you can't use wings off Prime, the mapper needs to have a list of all areas it can use wings on. To check this, do mc on and acl. Check the Prime continent list to see if the area you are in (as rl will tell you) the list. If it's not on the list - do ac prime to add it, and then mc off when you're done - and message Qwindor saying that the certain continent isn't on Prime as it should be, so he can update the map for everybody.

How do I tell it I have the celerity power (artefact or mhun racial ability)?

The mapper will automatically detect that you can move an extra room before the don't be hasty message and act accordingly.

How do I delete the map to start over?

Close Mudlet first, then go to:

• on Windows - your windows account folder, then the .config and the mudlet folder within,
• on Linux - your home folder, then the mudlet-data within,
• on Mac - your users folder, then the mudlet-data within,

Once there, go within the profiles folder - it'll list your list of profiles. Go within the relevant one, and delete the maps folder entirely.

That's it - start Mudlet, and your map state will be blank.

What is the difference between a room mark and a map feature?

Both can be used with the goto syntax (though slightly different) and both help finding certain rooms again, but where are the differences?

Room mark

• Room marks are akin to bookmarks. They help you remember a certain unique room and refer to it with another name.
• Your room marks will be migrated with map updates, meaning you can have your personal set of marks.
• They are set, listed and deleted with the *room mark*, *room marks* and *room unmark* commands respectively.
• To use goto with them, simply use *goto <room mark>*

Map feature

• Map features are used to mark similar rooms with a certain function. You usually don't care to which one of them you go, you simply needed the closest one.
• Map features are a feature of the crowdmap and lost with every map update. They should be added and maintained by mappers.
• They are set, listed and deleted with the *room create feature*, *feature list* and *room delete feature* respectively
• To use goto with them, use *goto feature <partial feature name>*

Embedding the map

Here is a script to place the map into a container and have it open each time you open the profile.

mapper = Geyser.Mapper:new({
  name = "mapper",
  x = "65%", y = 0, -- edit here if you want to move it
  width = "30%", height = "50%"
})

Settings

To see what options can you set in the mapper script, do mconfig. To change an option a true/false, do mconfig option on/off. Some options are specific to IRE games, some are applicable in general.

Available options:
Use Sprint? (sprint) false
Use a crowd-sourced map instead of IREs default? (crowdmap) true
Use Atavian Wings in Achaea? (duanatharan) true
Walk caravans? (caravan) false
Lock pathway exits? (lockpathways) true
Walk slowly instead of as quick as possible? (slowwalk) false
Lock all sewers? (locksewers) false
Lock all special exits? (lockspecials) false
Take off shackle? (shackle) false
Use Gallop? (gallop) false
Remove Wings after using them? (removewings) true
Show walking commands? (showcmds) true
Lock all wormholes? (lockwormholes) true
Speak non-default language for wings: (winglanguage)
Use Dash? (dash) false
Use Eagle Wings in Achaea? (duanathar) false
Check for new maps? (updatemap) true
Use Jester Runaway? (runaway) false

Aliases

common

goto

goto <id> - goes to a room of that id

goto <area> - goes to a specific area

goto <id> sprint/dash/gallop - goes to a place, sprinting, dashing or galloping whenever possible

goto <area> # - goes to an area - the number specifies which one exactly if more than one matches

goto feature <feature> - goes to the nearest room with the specified map feature

mpp

mpp [on|off] - toggles or sets mapper to be paused

mstop

mstop - stops the mapper completely

rf / room find

rf <name>, room find <name> - searches for a room of a given name

room marks

room marks - lists all the room marks the map has stored (your personal + default ones)

room mark

room mark <mark_name> <room> - adds a mark for a given room with the name. Doing 'goto <mark_name>' will take you directly there!

room unmark

room unmark <mark_name> - removes a mark with that name.

area list

area list - shows the known area list

room list

room list <area> - shows the list of rooms in an area

arealock

arealock, arealock <area> - displays a list of areas you can lock/unlock, can also give it an area name to filter by. If an area is locked the mapper will not attempt to walk through or go through any of the rooms in the area;

rl / room look

rl or room look - displays information about the room you're in

rl roomID or room look roomID - displays information on a given room ID (ie, rl 34)

rl room name or room look room name - displays information on a given room, by it's name (ie, rl tavern of blah)

• Note that this will override the in-game rl command - but you can use RL to still read the last message.

showpath

showpath roomID - shows you a path from where you are to another room (by it's ID)

showpath fromID toID - shows you a path from a given room to another given to another room

spe list

spe list - shows you the list of all known special exists

spe list filter - shows you a list of all known special exits, filtered by a command - for example spe list worm warp

mapping

Mapping new areas

The mapper relies on the in-game room IDs for it's own, and so it's best that you keep them in sync when creating new rooms as well - if you're in an unmapped room, 'rl' will tell you the rooms in-game ID. So when starting to map a new room in a new area, it'd best to create the new room with it's in-game ID at 0 0 0 coordinates, create the area, and move the room into the area - here are the exact steps necessary:

 mc on (this will start mapping mode on)

 rl <see the room ID> (find out the room ID you are in)

 rlc v<room id> 0 0 0 (create a new room with the ID of the one you're in - notice the lack of space between v and room ID)

 survey <see area name> (find out what is the area name you are in)

 area add <area name> (create this new area)

 room area <area name> (move your newly made room into the newly made area)

Proceed to walking about and automapping! Take a look at a small howto video to get ideas on solving mapping problems as well that you might run into.

Note:

The mapper will not break up areas for you, so you have the choice of selecting how do you define your areas. To start a new area, move the room into an area, and all subsequent rooms will be mapped in that area.

Sharing your map

You can use the map save custom alias to export your map as a .dat file, which you can share it with others. People who'd like to load your map will then do map load custom, select the map file from the file browser, and it will load it!

Some tips on mapping

• it's best to map in the 2D mode, because then you can select them en-masse and move them around, as well as doing other things
• you can move rooms en-masse by selecting them, right-clicking and hitting move (note that in older versions of mudlet, you don't want to select the one you're in and try and move, it would be difficult)
• when the mapper automatically makes a new room it is wise to issue a room area <area name> command to ensure the room is in the correct area.
• the automatic map view in Mudlet tries to do its best to get the rooms in a sensible order, however the Divine do not always make this easy. Sometimes no matter how much you move the rooms around you simply cannot get the map to look perfect; if this happens:
  • you can try to move the rooms around manually (take note of the above tip though)
  • if you see yourself in a room but cannot take the apparent exit (e.g. you try to go north but there is no exit north) you might have two rooms on top of each other; this can be a symptom of this problem
  • if you click on a room to walk to that room and you take what seems to be an improbably long path, it is possible some exits are not the direction they appear
  • the mapper knows about all the rooms even if Mudlet cannot display them in a way that is easy for us to see, the mapper can still use those rooms to get to or to auto walk through

Note: map save is your friend; you don't need to use it after each room you add, but it is suggested you use it after mapping one particular area or a smaller part of a large area; it is better to save more often than have to remap an area because of something totally unexpected.

Here's a short mapping video to get a sense of a possible way to map things.

mc - toggle mapping mode

Use: *mc or map create <option>*, where option can be "on" or "off". Turning the mapping mode on enables the mapping aliases, along with several automapping things (that rely on GMCP being enabled):

• room creation - if you enter a room that's not mapped yet, it'll map it
• exit creation - if there is an unmapped exit in the room, the mapper will auto-link it to another room (and create that other room if it doesn't exist yet)
• exit deletion - if the mapper knows about an exit that doesn't really exist, it'll remove it

rlc - create a room

Use: *rlc or room create <option>*, where option will specify the location of the new room. The new room will be auto-linked to the current one, be placed in the same area and take on the same environment type. If the mapper doesn't currently know where you are, you'll have to specify the exact coordinates that you'd like to place the room at (0x,0y,0z is a good place to start at). You can specify the location via several ways:

• relative direction - ie 'rlc n' will create the room north of you, 'rlc se s' will create the room south-east and south of you.
• exact coordinates - ie 'rlc 1 -5 10' will create the room at those exact coordinates. If the mapper doesn't know where you currently are, it'll also assume that you're located in that room now.
• exact coordinates + specific ID - ie 'rlc v34 0 0 0' will create a new room with that exact ID (best to use one from the game, which you can find by doing 'rl') at the center.
• partial coordinates - ie 'rlc 14x 5y' will create the room at 14x and 5y, but the same z-level you're on. You can can include all three of x,y,z coordinates or only one as you wish.

rc - move a room

Use: *rc or room coords [v<id>] <option>*, where option 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. Sample use:

• relative direction - ie 'rc nw' will move the room to be nw of the current location, 'rlc e s' will create the room east and south of the current location, and 'rc v34 w' will move the room ID 34 west
• exact coordinates - ie 'rc 1 -5 10' will move the current room to those exact coordinates. 'rc v12 8 3 -8' will move the room with ID 12 to 8x, 3y and -8z.
• partial coordinates - ie 'rc 14x 5y' will move the room to be at 14x and 5y, but the same z-level you're on. You can can include all three of x,y,z coordinates or only one as you wish

rld - delete a room

Use rld or room delete <option>, where option is the location or ID of the room you'd like to delete. Sample use:

• relative direction - ie 'rld n' will delete the room that's north of you
• exact room ID - ie 'rld 513' will delete the room with ID 513
• current room - ie 'rld' will delete the room you're currently in

rw - set room weight

Use rw <optional room ID or direction> <weight>, where option is the location or ID of the room whose weight you'd like to change. Sample use:

• relative direction - ie 'rw n 4' will set the room weight of the room that's to the north of you to four
• current room - ie 'rw 10' will set the room weight of the room you're standing in to 10
• by room ID - ie 'rw 2343 2' will set the room weight of room 2343 to 2

rwe - set exit weight

Use: rwe <optional room ID, otherwise current> <weight> <exit>, where the weight is a positive number (default for exits is 0). Setting a higher weight will make the exit be less likely to be used. Lastly, the exit can be a cardinal direction of either e,s,w,n,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.

• current room - ie 'rwe 1 n' will set the weight of the exit north to 1.
• current room - ie 'rwe 2434 0 e' will reset the exit weight of an east exit that leads out from the 2434 room.

rlk - link rooms

Use: *rlk or room link <option>*, where option will specify the room and exit to link with. You can also tack on 'one' at the end to make it be a one-way link. Examples:

• exact room ID and direction - ie 'rlk 351 n' will link the current room to room #351 via a north exit
• relative direction - ie 'rlk n' will link, if there is, a room to the north of this one to the one you're in
• 'rlk n one' will make an exit north one-way (so - from here to there, but not from there to here)

urlk - unlink rooms

Use: *urlk or room unlink <direction>*, where direction will specify the direction of the exit to unlink. This function will unlink exits both ways, or one way if there is no incoming exit.

Sample use:

• relative direction - ie 'urlk nw' will unlink the exit to the northwest, and from the northwest room to the southeast

rd - make doors

Use: *rd <optional room ID, or current if none> <direction> <door status>*. Direction can be one of the following: e,s,w,n,ne,se,sw,ne. 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.

Sample use:

• from current room - rd n open will add a one-way door north.
• from another room - rd 23 w closed will add a closed door leading west in room 23.

rcc - give room a letter

Use: *rcc <character> or rcc <letter> <room ID>*, where the character is one letter/number/symbol. Sample use:

• current room - ie 'rcc $' will put the dollar sign in the current room (good way to indicate a shop)
• another room somewhere on the map - ie 'rcc C 23434' will put the letter C onto room 23434
• using clear as character will clear the room letter - ie 'rcc clear' will remove any letter from the current room

spe - link rooms via special commands

Use: spe <other room> <command> or exit special <other room> <command>, where other room will specify the room to link with, and command the command to us to get to that room. Sample use:

• relative direction - ie 'spe n push rock' will go to the room that's north of you by doing 'push rock'
• exact room ID - ie 'spe 125 pull lever' will go to room 125 from the current one by pulling a lever

You can also specify the script to do code for you, by starting the exit command with script: - for example:

• run a script:

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

• run a script with a delay:

  spe 125 script: send("pull lever") mmp.customwalkdelay(10) tempTimer(10, [[enter gate]])

If you'll be making use of mmp.customwalkdelay - make sure your script doesn't make use of room look or anything of that sort, because it will reset and make the mapper re-path (technical reason for this is because it'll be thinking it moved on already, so when it sees that it "ended up" not where it thought it was not, it'll retry).

You can also make use of temporary triggers in your special exits as well - if you are, you must store the trigger IDs in mmp.specials table - this way if the user decides to cancel walking via mstop, they will be deleted properly. Here is a through example of the Arcadia exit in Achaea, which requires opening the path by saying a word, waiting, and then entering - a path that might already be open and for which saying the word won't have any effect either. The script below is what was used to make it - it is split into multiple lines here for readability, but the command must all be on one line:

  spe 19775 script: send("say Arcadia") send("enter archway") mmp.customwalkdelay(12) 
  if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end 
  mmp.specials.arcadiaarchway = tempExactMatchTrigger("The arches slowly solidify before your eyes, what was mere light becoming the cool white marble of a tall stone archway.", 
    [[if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end
      if not mmp.paused then send("enter archway") end
    ]])
  if mmp.specials.arcadiaql then killTrigger(mmp.specials.arcadiaql) end
  mmp.specials.arcadiaql = tempExactMatchTrigger("You step through a shimmering marble archway.",
    [[if mmp.specials.arcadiaql then killTrigger(mmp.specials.arcadiaql) end
      if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end
    ]])

spev - link two remote rooms via special commands

Use: spev <from room> <to room> <command>. This different than spe, which allows you to link only the current room to another room - this command doesn't require you to be in the starting room.

• from room - the starting room for the special exit
• to room - the ending room on the other side of the special exit
• command - the command linking these two rooms together - ie "enter portal". You can also specify a script to run similar to spe.

spe clear - unlink all special command links

Use: *spe clear or exit special clear <option>*, where option is the location or the ID of the room you'd like to clear all special exits in. Sample use:

• relative direction - ie 'spe clear n' will delete all special exits in the room that's north of you
• exact room ID - ie 'spe clear 513' will delete all special exits in room with ID 513
• current room - ie 'spe clear' will delete all special exits in the room you're currently in

room area - move room to another area

Use: *room area <different area>* will move the current room to another area you're in. Sample use:

• area name - ie 'room area glomdoring' will move the room you're currently standing in to Glomdoring. You can also specify another room to move with 'room area v# <area>', ie 'room area 1 my new area'
• area id - ie 'room area 44' will move the room to the area ID 44

room label - add a label to a room

Use: *room label <optional another room ID> <optional foreground color> <optional background color> my message*. Examples of using this:

• room label the room I'm in
• room label 342 this is a label in room 342
• room label green this is a green label where I'm at
• room label green black this is a green to black label where I'm at
• room label 34 green black this is a green to black label at room 34

area add - create a new area

Use: *area add <area name>* will create a new area and automatically give it an ID. Sample use:

• area name - ie 'area add Mrr city' will create a new area called such

area rename - rename an area

Use: *area rename <new area name>* will rename the current area you're in to the new name. Sample use:

• area name - ie 'area rename Bobcat place* will call the area you're in like so from now on

area delete - delete an area

Use: *area delete <area name>* 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, this 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.

Sample use:

• by area name - ie *area delete Bobcat place* will delete that area

cancel area deletion

Use: *cancel area deletion* stop area deletion. This will not restore deleted rooms - 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.

Sample use:

• just one command - ie *cancel area deletion*.

area labels - view/delete labels in an area

Use: *area labels <area name>* will show the labels in the given area. Click on the small blue minus sign to delete the label.

aca - add area to continent

This alias will assign an area to belong to a continent. If an area belongs to another continent, it'll be moved. Currently, this feature is only used in Achaea for Eagle or Atavian wings (the area needs to be set as being on "Prime" continent).

Use:

• aca <continent> - adds the current area to a continent
• aca <continent> <area name> - adds the given area to a continent
• aca <continent> <area ID> - adds the area by area ID to a continent

acl - list continents data

Use: acl or area continents - lists which areas are in which continents are the mapper knows them. Currently, this feature is only used in Achaea for Eagle or Atavian wings.

map save - save the map

Use: *map save <optional name>* will save all of the map. Sample use:

• default map - ie 'map save' will save the map with the default name as the latest one
• map name - ie 'map save map before experiment' will save the map with that name
• custom - ie 'map save custom' will export the map as a file, so you can share it with others

You can also save the map as text (JSON) by using map save json or map save all (in both normal and JSON). For example:

• default map - ie 'map save json' will save the map with the default name as the latest one, 'map save all' will do it in both.
• map name - ie 'map save json map before experiment' will save the map with that name
• custom - ie 'map save json custom' will export the map as a file, so you can share it with others

map load - load the map

Use: *map load <optional name>* will reload the map. Sample use:

• default map - ie 'map load' will load the latest saved map (it may be a named one)
• map name - ie 'map load before experiment' will load the map with that name
• custom - ie 'map load custom' will load a map .dat file as you select it
• as json - 'map load before experiment.json' - appending '.json' will make it load as json

map delete all - clear the whole map

Use: *map delete all* delete all areas and rooms of the map. Requires confirmation before actually clearing everything.

delete known stockrooms

Use: *delete known stockrooms* will unlink all known shops (marked with $) from their stockrooms, so the $ and the down exit triangle don't overlap each other.

clear continent data

Use: *clear continent data* will delete all of the continent data stored for the map.

delete suffixed periods

Use: *delete suffixed periods* will delete all the periods at the end of room names - which should just be stored as proper titles in the mapper, without the ending dot. It makes dealing with them (for use in locating abilities and etc) easier.

find single exits

Use: *find single exits* will locate all one-way exits for you. These can either be legitimate one-way exits, or they could be unmapped rooms that you want to visit, or they could be half-linked exits that you accidentally made via deleting rooms and mapping. You can click on the lines to go to those rooms.

show char marks

Use: *show char marks* will show you a list of character marks made with rcc available on this map.

feature create

Use: *feature create <feature> [char <room character>]* 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.

feature list

Use: *feature list* lists all map features created via feature create and the associated room characters

feature delete

Use: *feature delete <feature>* deletes a map feature and removes it from all rooms.

room create feature

Use: *room create feature [v<room id>] <feature>* or *rcf [v<room id>] <feature>* adds 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 that there is no space between the v and the ID).

room delete feature

Use: *room delete feature [v<room id>] <feature>* or *rdf [v<room id>] <feature>* 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 that there is no space between the v and the ID).

feature migrate

Use: *feature migrate* if the command is set up for your game, it will try to migrate certain character marks to map features. Ideally, this should be used only once per game and afterwards map features should be added instead of character marks.

API

using settings

checking a setting

Check mconfig settings using mmp.setting.<key> or mmp.settings[<key>]. For example, mmp.setting.sprint or mmp.settings["sprint"] will tell you if you have the Sprint option activated or disabled.

retrieving the list of settings

mmp.settings:getAllOptions() will return you a key (option) - value (option setting) table of all of the available settings. You can use this to check which options are available.

setting a setting

To set a value, use mmp.settings:setOption(option, value).

functions

mmp.anytolong

mmp.anytolong(exit)

converts an exit name to its long version.

Parameters

• exit:

The exit abbreviation that needs to be converted. This must be a lower case string.

Return value

• longExit:

The long version of the exit name as a string.

Example

--This would return "north" from the function
mmp.anytolong("n")
--This would return "south" from the function (to be sure that you use the long version)
mmp.anytolong("south")

mmp.anytoshort

mmp.anytoshort(exit)

converts an exit name to its short version.

Parameters

• exit:

The exit abbreviation that needs to be converted. This must be a lower case string.

Return value

• shortExit:

The short version of the exit name as a string.

Example

--This would return "n" from the function
mmp.anytoshort("north")
--This would return "s" from the function (to be sure that you use the long version)
mmp.anytoshort("s")

mmp.customwalkdelay

mmp.customwalkdelay(time)

Clears and extends the default walk re-try delay to a custom time, specified in seconds. This is helpful to trigger on, or use in special exit scripts in cases where you need to wait an abnormal amount of time before continuing on your journey.

If you'd like to cancel the customwalkdelay and move on, call mmp.move(). Note that if a GMCP room event is received (this can be triggered with QL or other commands) the mapper then will attempt to repath, as it would have considered to have moved on and expects to be at the next room (thus don't cause this to happen).

Parameters

• time:

Time in seconds to set the delay for.

Example

if a special exit somewhere requires you to wait after trying to enter, use a scripted special exit with a delay:

 spe # script: send("dance around circle") mmp.customwalkdelay(10)

you could also use it in a trigger, however the spe method is preferred:

-- trigger script:
mmp.customwalkdelay(10)

mmp.deleteArea

mmp.deleteArea(name,exact)

Deletes an area from the map, if the given name is distinct. If not it shows a clickable list of deletable matches.

Parameters

• name:

The name of the area that should be deleted. This is a string parameter.

• exact:

Boolean value, that describes if the name is the exact (true) or partial (false) name.

Raised events

• mmp areas changed

Example

--This would attempt to delete "Hashan" from the map (Achaea)
mmp.deleteArea("Hashan", false)
--[[
Output:
(mapper): Which one of these specifically would you like to delete?
  Hashan, the City of (Sewers)
  Hashan, the City of (Seneschal Complex)
  Hashan, the City of
]]

--This would delete "Hashan, the City of" from the map (Achaea)
mmp.deleteArea("Hashan, the City of", true) --if you made the second argument false, it'd give the same output as above

mmp.deleteLineP

mmp.deleteLineP()

Deletes the current line and the following prompt.

Example

--[[
Sample input:
3620h, 3447m, 15755e, 21980w cexb-
Your enhanced senses inform you that Sidai has entered At the southern gates of Hashan nearby.
3620h, 3447m, 15755e, 21980w cexb-

Trigger:
^Your enhanced senses inform you that (\w+) has entered (.+) nearby\.$
]]

mmp.deleteLineP()
cecho("WARNING! "..matches[2].."nearby! ("..matches[3]..")")

--[[
Output:
3620h, 3447m, 15755e, 21980w cexb-
WARNING! Sidai nearby! (At the southern gates of Hashan)
]]

mmp.echo

mmp.echo(what)

Prints the argument with a prefixed "(mapper): ".

Parameters

• what:

The message that should be printed.

Example

mmp.echo("We arrived at our destination.")
--[[
Output:
(mapper): We arrived at our destination.
]]

mmp.echoAreaList

mmp.echoAreaList()

Prints a list of all known areas. Each name is clickable to display its room list.

Example

mmp.echoAreaList()
--[[
Output of Midkemia-Online (no longer extant on IRE - example needs updating...!):
List of all areas we know of (click to view room list):
     2 Caldara
     3 Human Introduction
     4 Krondor
   (...)
   100 Fifth Circle of Hell
   102 Eagles Reaches
   108 Ruins of Veilgarden
]]

mmp.echonums

mmp.echonums(roomname)

Prints the first three possible room IDs for the given room name. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there.

Parameters

• roomname:

Name of the room of which the IDs should be displayed. This must be a lower case string.

Example

mmp.echonums("The Crossroads")
--[[
Output:
4472, 4895, 6162, ...
]]

mmp.echonums("foobar")
--[[
Output:
?
]]

mmp.locateAndEcho

mmp.locateAndEcho(room, person, area)

Prints the first three possible room IDs for the given room name, and the area(s) relevant as well if the is not used in the function otherwise it will only print the room numbers for the given area. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there. This is good to use if you can narrow down the exact in game area with whatever skill you use as shown with the difference between the first and second example.

Fills the mmp.ndb with relevant information as well.

Parameters

• room:

Name of the room of which the IDs should be displayed. This must be a lower case string.

• person:

Name of the person you are locating for the person for the person location tracker.

• area:

Matches the in game area based on the name of the area populated from the room gmcp information.

Example

mmp.locateAndEcho("Inside the World Tree", "Person")
--[[
Output:
  (52454, 53005, 53544, ...)
From your knowledge, that room might be in The collar of Frysta, or The collar of Bjarndyr, or Village of Qerstead, or Radak's Hold, or Loramere, or Central Wilderness, or Lhitsu forest, or Village of Myrinia, or Sarave Foothills, or The collar of Veior, or fathomless expanse of the World Tree, or Ioje compound, or Valley of Kuthalebak, or Kunpai Island, or Pri'alysh Moor.
]]

mmp.locateAndEcho("Inside the World Tree", "Person", "the Central Wilderness")
--[[
Output:
  (2898)
From your knowledge, that room is in Central Wilderness.
]]

mmp.locateAndEchoSide

mmp.locateAndEchoSide(room, person)

Prints the first three possible room IDs for the given room name, and the area(s) relevant as well. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there. This will display to the side of the line triggered as shown below.

Fills the mmp.ndb with relevant information as well.

Parameters

• room:

Name of the room of which the IDs should be displayed. This must be a lower case string.

• person:

Name of the person you are locating for the person for the person location tracker.

Example

Triggered line:

You seek out the mind of Krizal and an image of The Crossroads appears in your mind.

mmp.locateAndEcho("The Crossroads", "Krizal")
--[[
Output:
You seek out the mind of Krizal and an image of The Crossroads appears in your mind.  (4472)  (Hashan)
]]

mmp.gotoRoom

mmp.gotoRoom(room ID, sprinttype)

Similar to goto <room ID>, this'll start speedwalking to the given room.

Parameters

• room ID:

The room ID to head to.

• sprinttype:

(optional): how to speed up the way there - can be gallop, sprint, dash, runaway, glide.

Example

-- go to room #5
mmp.gotoRoom(5)

-- go to the room Bob was last located in
mmp.gotoRoom(mmp.getnums(mmp.pdb["Bob"])[1])

-- go to room #5, galloping where possible
mmp.gotoRoom(5, "gallop")

mmp.echoRoomList

mmp.echoRoomList(area name)

Prints a list of all known rooms in a given area. Each name is clickable to go to that room.

Parameters

• area name:

The name of the area in which rooms should be listed.

Example

-- list rooms from area "main"
mmp.echoRoomList("main")

mmp.getShortestOfMultipleRooms

mmp.getShortestOfMultipleRooms (rooms)

Returns the closest room from a table of multiple room ids

Parameters

• rooms:

Table of two or more room ids.

Example

-- return the closest of three different rooms
rooms = {1,2,3}
closestRoom = mmp.getShortestOfMultipleRooms(rooms)
print(closestRoom)

mmp.getAreaName

mmp.getAreaName(roomid)

Returns the area name that the room belongs to, or "?" if it is unknown.

Parameters

• roomid:

Room ID you'd like to know the area of.

Example

-- show the area that room 31434 belongs to
print(mmp.getAreaName(31434))

mmp.roomFind

mmp.roomFind(query, lines)

Displays rooms that match your query. The room number that is output will autowalk to the location when clicked. The area that is output will show the shorted path to the room.

Parameters

• query:

Name or partial name of the room that you are trying to find.

• lines:

The number of rooms that will be output to your screen. Default is 30. Can also send 'all' to list all room matches.

Example

mmp.roomFind("forest")
mmp.roomFind("forest", "all")
mmp.roomFind("forest", "40")

mmp.gotoFeature

mmp.gotoFeature(partialFeatureName, dashtype)

Finds the sortest path to the nearest feature matching the (partial) map feature name. If given, it will also use a dashtype.

Parameters

• partialFeatureName:

Partial name of a map feature to go to. If the name matches a map feature exactly, it's chosen before any partial matching is attempted.

• dashtype:

One of the defined movement types which allow skipping a number of rooms in a straight line.

Example

mmp.gotoFeature("junk")
mmp.gotoFeature("wilder", "gallop")

mmp.createMapFeature

mmp.createMapFeature(featureName, roomCharacter)

Creates a new map feature with the given name and optionally associates a character mark with the map feature. This function will not associate the feature with any rooms, but instead, it whitelists the map feature for future use.

Parameters

• featureName:

Name of the map feature to create.

• roomCharacter:

Optional parameter to set the character mark to use when adding the map feature to a room.

Return value

• success:

Returns true if the creation was successful, otherwise nil.

Example

mmp.createMapFeature("savehouse")
mmp.createMapFeature("junk", "J")
mmp.createMapFeature("wilderness", "W")

mmp.listMapFeatures

mmp.listMapFeatures()

Prints the list of map features to the main console.

Return value

• success:

Returns true if the listing was successful, otherwise nil.

Example

mmp.listMapFeatures()

mmp.roomCreateMapFeature

mmp.roomCreateMapFeature(featureName, roomId)

Creates a whitelisted map feature in a room. If the room ID is not given, mmp.currentroom is used. If the map feature is associated with a character mark, the mark will be set on the room, overwriting the existing one.

Parameters

• featureName:

The name of a whitelisted map feature to create in the room.

• roomId:

Optional parameter to identify the room where the map feature should be created. If it is not given mmp.currentroom is used.

Return values

• success:

Returns true if the creation was successful, otherwise nil.

Example

mmp.roomCreateMapFeature("junk")
mmp.roomCreateMapFeature("wilderness", 12358)

mmp.roomDeleteMapFeature

mmp.roomDeleteMapFeature(featureName, roomId)

Deletes a map feature from a room. If the room ID is not given, mmp.currentroom is used. If the room carries the associated character mark, it will be removed and the character mark of a random remaining map feature will be used.

Parameters

• featureName:

The name of a map feature to delete from the room.

• roomId:

Optional parameter to identify the room where the map feature should be deleted. If it is not given mmp.currentroom is used.

Return values

• success:

Returns true if the deletion was successful, otherwise nil.

Example

mmp.roomDeleteMapFeature("junk")
mmp.roomDeleteMapFeature("wilderness", 12358)

mmp.getRoomMapFeatures

mmp.getRoomMapFeatures(roomId)

Returns a list of map features in the room. If the room ID is not given, mmp.currentroom is used.

Parameters

• roomId:

Optional parameter to identify the room of which the map features should be returned. If it is not given mmp.currentroom is used.

Return values

• roomMapFeatures:

Returns a list of map features in the given room. If an error occurred, nil is returned.

Example

mmp.roomCreateMapFeature("junk")
mmp.getRoomMapFeatures() -- returns { "junk" }


mmp.roomCreateMapFeature("wilderness", 12358)
mmp.roomCreateMapFeature("harbour", 12358)
mmp.getRoomMapFeatures(12358) -- returns { "wilderness", "harbour" }

mmp.deleteMapFeature

mmp.deleteMapFeature(featureName)

Deletes the whitelist entry of a map feature from the map. This also leads to the deletion of the map feature from all rooms.

Parameters

• featureName:

The name of the map feature that should be deleted from the map.

Return values

• success:

returns true if the deletion was successful, otherwise nil

Example

mmp.deleteMapFeature("junk")

mmp.getMapFeatures

mmp.getMapFeatures()

Returns a table of whitelisted map features for this map and their associated character marks.

Return values

• mapFeatures:

The list of map features that are whitelisted in this map and their associated character marks.

Example

mmp.createMapFeature("savehouse")
mmp.createMapFeature("junk", "J")
mmp.createMapFeature("wilderness", "W")

mmp.getMapFeatures()
-- [[
returns {
  savehouse = "",
  junk = "J",
  wilderness = "W"
}
]]

mudlet events

• mmapper started walking - raised before starting autowalking
• mmapper failed path - tried to go from A to B, but failed because there is no known path (or we were walking, got moved offcourse, and can't get to the destination anymore)
• mmapper arrived - arrived at our destination successfully
• mmapper stopped - mapper's stop function was called (this will be raised anytime it was, even if we weren't moving)
• mmapper updated pdb - mmp.pdb table was updated with new data
• mmapper updated map - raised when the mapper loads a new map in with loadMap()
• mmapper map reloaded - raised when the map is reloaded
• mmapper went inside - raised when you go inside in Achaea
• mmapper went outside - raised when you go outside in Achaea
• mmapper changed continent - raised when you change continents in Achaea
• mmp logged in - raised when logged in to determine IRE game
• mmp lost def - raised when a defence is lost
• mmp got def - raised when a defence is gained
• mmp areas changed - called when list of areas is edited
• mmp link externals - raised before a path starts getting computed. You can use this event to add in special exits that you'd like the mapper to consider. Added in 14.4.1.
• mmp clear externals - raised after a path is computed. Use this event to remove special exits that you've added with 'mmp link externals'. Added in 14.4.1.
• mapperScriptLoaded - raised after the mapping script itself is loaded, enabling other scripts to work with it. Added in 24.12.1.

Developers

Code is hosted in Git on GitHub, ire-mapper-script. If you'd like to help develop, please feel free to submit a pull request!

Credit to: Sidd (for sharing his own mapping aliases that came before any documentation existed), keneanung (contributing to the coding, adding goto <area> and many other things), Wyd for the options system.

What else needs to be done

General things that need work are triggers for where room detection is necessary - player-locating abilities, shrine defilement warnings, mindsense area reports, etc. The general format is that the room ID should be prefixed to the line the room name is given + be made clickable - so the player can click on it and go. An example is provided for the Lusternian scent ability that implements this. Also needs to recognize the need to swim, right now if you don't have waterwalking - it'll loop trying to walk. Another small problem is that if it gets off the path once, it'll keep saying that it ended up off the path, and not realize when it arrived at the location properly (but it does arrive).

I've also started a bit on a person db - it stores the last known locations of players. This is something that is useful to everybody, so it's best that we don't have to keep reimplementing ourselves but use a common version. This requires more triggers to feed it's hunger for data as well!

• track which rooms you've visited, and have an option to highlight unvisited rooms
• show only game-relevant mconfig options