IRE mapping script

This is the Lua component to make the Mudlet Mapper work for IRE games. You'll need to import the xml below in order for autowalking to work on Achaea, Aetolia, Lusternia, Imperian, or Midkemia Online. See the download section to get started!

It has many features such as:

• automatic repathing if you get offcourse
• locking of whole areas
• auto-swimming
• mapping
• scriptable exits

The script is written and maintained by Vadi, with Qwindor doing the notable mapping in Achaea. Have feedback, comment or a suggestion? Please comment here!

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

Download

latest version (updated very often) - news feed for updates, or read 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)

Note:

For Mac users this means you must be using at least the download: 2.x release

• import this script
• make sure you're connected to 'achaea.com', 'lusternia.com', 'aetolia.com', 'imperian.com' or 'midkemiaonline.com' if you'd like Mudlet to download a map for you
• done!

Updating

To update the mapper script, firstly delete all the Mudlet Mapper trigger, alias and script folders. Then, download the new xml and import it.

---

To make Mudlet re-download the map, close Mudlet, find the ~/.config/mudlet/profiles/<your profile>/map folder and delete it. ~ is your home folder. Start Mudlet again, click the Map button and it'll download the latest map.

Note: On Windows its %USERPROFILE%/.config/mudlet/profiles/<your profile>/map

Mapper changelog is available here.

Support

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

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

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 <room #> - adds a mark for a given room with the name. Doing 'goto ' will take you directly there!

room unmark

room unmark - 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

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

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

mapping

It's best that you always have the latest version of Mudlet 2.0 release candidate installed while mapping (especially not rc4, which was buggy), along with the latest version of this script - because both are still very much in progress and are updated and improved often. Feel free to submit feedback on the mapping script on the forums, or even improve it yourself as all the code is available. General Mudlet Mapper feedback is welcomed as well.

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
• when moving around rooms via selection, do not include the room you're currently in, it'll go wild. If this is a problem, then move the current room out to wild coordinates and then move it back
• 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

IMPORTANT: 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.

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 - ie:

mc on

rl <see the room ID>

rlc v<room id> 0 0 0

survey <see area name>

area add <area name> (this will create the area)

room area <area name> (this will move the room to the new 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.

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

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

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

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

• run a script: <lua>spe 125 script: sendAll("pull lever", "enter gate")</lua>
• run a script with a delay: <lua>spe 125 script: send("pull lever") mmp.customwalkdelay(10) tempTimer(10, enter gate)</lua>

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:

<lua>

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

</lua>

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. Sample use:

• area name - ie 'area delete Bobcat place* will delete such an area

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.

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

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

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.

API

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

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

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

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

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: <lua> -- trigger script: mmp.customwalkdelay(10) </lua>

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

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

mmp.deleteLineP

mmp.deleteLineP()

Deletes the current line and the following prompt.

Example

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

mmp.echo

mmp.echo(what)

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

Parameters

• what:

The message that should be printed.

Example

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

mmp.echoAreaList

mmp.echoAreaList()

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

Example

<lua> mmp.echoAreaList() --[[ Output of Midkemia-Online: 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

]] </lua>

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

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

mmp.echonums("foobar") --[[ Output: ? ]] </lua>

mmp.locateAndEcho

mmp.locateAndEcho(roomname, 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.

Fills the mmp.ndb with relevant information as well.

Parameters

• roomname:

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

Example

<lua> mmp.locateAndEcho("The Crossroads", "Person") --[[ Output:

 (4472)

From your knowledge, that room might be in Shallam, the City of, or Hashan, the City of, or Jaru. ]]

</lua>

mmp.gotoRoom

mmp.gotoRoom(room ID)

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

Parameters

• room ID:

The room ID to head to.

Example

<lua> -- go to room #1 mmp.gotoRoom(5)

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

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

<lua> -- list rooms from area "main" mmp.echoRoomList("main") </lua>

mudlet events

• 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

Developers

Code is hosted on a bzr branch in launchpad.net, mapper-lua. If you'd like to help develop, please feel free to create a branch, add your changes, and then request a merge of your code!

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)

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!