[Home] [Downloads] [Search] [Help/forum]


Register forum user name Search FAQ

Gammon Forum

[Folder]  Entire forum
-> [Folder]  MUSHclient
. -> [Folder]  Plugins
. . -> [Subject]  MUSHclient generic graphical mapper module

MUSHclient generic graphical mapper module

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page


Pages: 1 2  3  4  5  6  7  8  9  10  11  12  13  14  15  16  17  

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Fri 12 Mar 2010 03:26 AM (UTC)

Amended on Sun 18 Aug 2019 07:05 AM (UTC) by Nick Gammon

Message
Nick's mapper engine


I am pleased to release a generic "MUD mapper" engine. It is the product of a considerable amount of work that started off as a mapper for SmaugFUSS, then was modified to work with Achaea and Imperian. However eventually I realised the best thing was to abstract out the "core" mapping part (the non-MUD-specific part) and let individual MUDs just interface with it.

Features



  • Draws in realtime your current room, and the rooms around you, by "walking" outwards from your current location.

  • For each known room a box is drawn to represent the room, and lines for each exit.

  • If the exit room is known then the process is repeated, potentially drawing hundreds of connected rooms.

  • Under control of the calling plugin each room can be individually coloured (e.g. to show shops, trainers, or just to indicate terrain type like water, desert).

  • You can zoom in to see more clearly, or zoom out to see "the big picture".

  • The mapper can be dragged around the screen with the mouse.

  • You can configure its size to be what you desire.

  • You can configure the colours used to display things like known rooms, unknown rooms, etc.

  • You can configure the depth of the search - the bigger the depth the slower it runs, but you see more detail.

  • It is fast, even zoomed right out on Imperian, and displaying over 400 rooms at once, it takes about 0.07 seconds to draw. With 100 rooms visible (zoomed in) it takes about 0.01 seconds to draw.

  • The room name, and area name (if supplied) are displayed on the map.

  • You can LH click on any visible room to speedwalk to that room by the shortest route.

  • Speedwalking is "throttled" so that it only moves from one room to the next once you arrive there. Even then you can add in a configurable delay, in case the MUD requires it.

  • Speedwalking auto-cancels if it detects it has ended up in an unexpected room number enroute.

  • There is a generic "room finder" built in. This can be called by the owner plugin to detect the shortest path to any room - you specify in the calling plugin the condition. For example, nearby shops, trainers, portals, or match on text in the room name. Found rooms can be walked to by just clicking on the hyperlink in the list of found rooms.

  • If the player RH clicks on a room a user-supplied callback is called. This can be used to implement other behaviour. For example, in the Imperian plugin, I made a bookmark feature, so players can bookmark places of interest. You can then quickly go to any of your bookmarked rooms.

  • If you hover over a room with the mouse a plugin-defined message appears (e.g. room name, terrain type, exits)

  • Recently trod paths are shown with a thicker line, so you can see where you have come from.

  • You can colour different areas in different ways, for example you might dim out all but the current area to make the current area stand out more.

  • It is designed to be "MUD neutral". This is done by having the mapper "call back" to the calling plugin whenever it needs room details. The calling plugin can then read a database, get information from memory, or some other method to fill in things like the room name, desired colour, and other details.



How to use


Tutorial: http://www.gammon.com.au/forum/?id=12635

First you install it in a plugin like this:


require "mapper"


Then in the plugin installation function you initialise the mapper like this:


mapper.init { config = config, get_room = get_room, show_help = OnHelp, room_click = room_click  } 
mapper.mapprint (string.format ("MUSHclient mapper installed, version %0.1f", mapper.VERSION))


This specifies some general configuration (like colours, mapper size), and a few callback functions.


  • config is table of colours and other values used to control the mapper's behaviour. The plugin can serialise that to the save_state file to preserve settings between sessions.

  • get_room is called when the mapper needs to know details about a room.

  • show_help is called if the player clicks on the "?" help button on the map.

  • room_click is called if the player RH-clicks on a room.


A simple get_room function might look like this:


function get_room (uid)
 
  local room = load_room_from_database (uid)
  
  if not room then
     return nil  -- room does not exist
  end -- if

  room.hovermessage = room.name   -- for hovering the mouse

  -- desired colours

  room.bordercolour = ColourNameToRGB "lightseagreen"
  room.borderpen = 0 -- solid
  room.borderpenwidth = 1
  room.fillcolour = ColourNameToRGB "green"
  room.fillbrush = 0 -- solid

  -- obviously you would look these up in practice
  room.area = "Darkhaven"
  room.exits = { n = 21001, s = 21002, se = 21003 }

  return room

end -- function


The mapper uses the colours you supply to draw this room. It then uses the exits table to work out which rooms are connected to this one. So in this example the process would be repeated as it drew rooms 21001, 21002 and 21003 (and then repeated again for whatever exits they had).

In practice the function would be more complex, as you work out colour based on terrain or type of room, you would look up area names and exits, and have a more complex "hover" message. However it illustrates the general idea.

Drawing the map


The map is drawn when the plugin wants it to be, by calling the draw function, like this:


mapper.draw (uid)


So once you detect you have changed rooms (however this is done) and you know the new room number or identifier, you just call "draw" to have it drawn. This will cause the mapper to first call back for information about the supplied room number (as described above) and then for each of that room's exits.

Various other function are exposed for use by the caller, such as hide (), show (), zoom_in (), zoom_out (), all of which might be called by aliases in the plugin.

Generic searching


The code below illustrates one of the searches I put into the Imperian/Achaea plugin. It reads from the database doing a full-text search for whatever words you supply in the search alias, getting a list of matching rooms.

It then calls the mapper.find function, passing down the starting room, and a callback function. The mapper then calls this function for each room it finds as it "walks" outwards from the starting room, asking if this room satisfies the condition. If it returns true (or a non-nil value) then that room will be displayed in the "matching rooms" list. It can also indicate if the search is to continue by returning true or false as the second return value. This lets the mapper know whether to keep searching or not. You might return false if you knew all desired rooms had been found, or if you simply only wanted to find one (e.g.. the nearest shop). The count, if supplied, is used as a hint message to the player that some rooms matched the condition, but couldn't be walked to in the scan distance.


function map_find (name, line, wildcards)
 
  local rooms = {}
  local count = 0
  
  -- find matching rooms using FTS3
  for row in db:nrows(string.format ("SELECT uid, name FROM rooms_lookup WHERE rooms_lookup MATCH %s", fixsql (wildcards [1]))) do
     rooms [row.uid] = true
     count = count + 1
  end   -- finding room
  
  -- see if nearby
  mapper.find (
    function (uid) 
      local room = rooms [uid] 
      if room then
        rooms [uid] = nil
      end -- if
      return room, next (rooms) == nil
    end,  -- function
    true,  -- show vnum
    count  -- how many to expect
    )
  
end -- map_find




Download


The mapper module is available here:

http://github.com/nickgammon/mushclient/blob/master/lua/mapper.lua

It may have bugs, new versions will be uploaded from time to time. More documentation is in the source. I will publish an example plugin that uses it shortly.

[EDIT] Changed on 13 March to reverse the sense of LH and RH clicks.

See http://www.gammon.com.au/forum/?id=10138&page=7 (page 7 of this thread) for a suggested plugin that could be used on MUDs that don't directly supply room numbers.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #1 on Fri 12 Mar 2010 03:28 AM (UTC)

Amended on Fri 12 Mar 2010 04:59 AM (UTC) by Nick Gammon

Message

Examples:

Note the yellow desert surrounding the city.

Note the shops which are the brown squares with the different texture.


- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #2 on Fri 12 Mar 2010 03:31 AM (UTC)

Amended on Fri 12 Mar 2010 04:21 AM (UTC) by Nick Gammon

Message
Example searches...

Bookmarks search


> mapper bookmarks

 
Antioch Shuk (13224) - 7 rooms away [Assorted goods such as vials, weapons, etc.]
Antioch Commodity Tent (14333) - 7 rooms away [Commodity vendor]
Divine Gifts (13233) - 8 rooms away [Designs, flowers, jewelry]
Clothing tent (13805) - 8 rooms away [Clothing patterns vendor]


Shops search



> mapper shops

Gathering tent (13276) - 6 rooms away [Newsroom]
Antioch Treasure Tent (13284) - 6 rooms away [Bank]
Antioch Shuk (13224) - 7 rooms away [Shop]
Antioch Commodity Tent (14333) - 7 rooms away [Shop]
Divine Gifts (13233) - 8 rooms away [Shop]
The Antiochian Refinery (11801) - 8 rooms away [Shop]
Clothing tent (13805) - 8 rooms away [Shop]
Forge of the Lion (13231) - 8 rooms away [Shop]
The Desert Mirage (13232) - 8 rooms away [Shop]
The Stehl Rose (2496) - 9 rooms away [Shop]
Curious Wanderer (2495) - 9 rooms away [Shop]



Full-text search



> mapper find garden


A garden of rock and wind (5356) - 14 rooms away
A garden of sea urchins and coral (14838) - 30 rooms away
The center of the garden (7227) - 39 rooms away
Overlooking a small garden (23865) - 43 rooms away

...

A white pebble path through the garden (23866) - 44 rooms away
Elmwood adjoining garden of a tavern (964) - 45 rooms away
There were 100 matches which I could not find a path to within 50 rooms.




Areas search

(Finds the nearest room in a different area to the current one)



> mapper areas

Victory Circle (13254) - 1 room away [the City of Antioch]
Under the Shuk (14187) - 8 rooms away [the Sewers of Antioch]
Amid the dunes (11263) - 11 rooms away [the Theroc Encampment]
Heartlands nearing desert's edge (264) - 11 rooms away [the Heartlands]

...

There were 95 matches which I could not find a path to within 50 rooms.


- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Garrion   (21 posts)  [Biography] bio
Date Reply #3 on Fri 12 Mar 2010 06:29 AM (UTC)
Message
Hi Nick,

I love the look of this system. I play a Mud that does not have unique room names or numbers. I am guessing this system won't work on Mud's like this...

Please tell me I am wrong? I would love something like this.

Thanks,
Garrion.
[Go to top] top

Posted by David Haley   USA  (3,881 posts)  [Biography] bio
Date Reply #4 on Fri 12 Mar 2010 02:09 PM (UTC)
Message
You would need some sort of cooperation from the MUD to provide unique identifiers for the rooms. It is very complicated to guess at a room's unique identity, and I don't think Nick has code to do that. What kind of MUD do you play? I'm a little surprised that there are no unique rooms. Or did you mean that there are occasionally rooms that aren't unique? (How can a physical location not be unique?)

David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top

Posted by Larkin   (278 posts)  [Biography] bio
Date Reply #5 on Fri 12 Mar 2010 02:53 PM (UTC)
Message
I'm very excited to see this work being done in such a cool way.

I'm a little concerned by the exits that do not connect on the map window, hoping that will be fixed eventually.

I'll be glad to provide you with a copy of my own mapper script for Lusternia, based on the MudBot module, as it has some nice features for locating people on the map, auto-locating you when you get lost or teleport, and things like that...
[Go to top] top

Posted by Twisol   USA  (2,257 posts)  [Biography] bio
Date Reply #6 on Fri 12 Mar 2010 03:38 PM (UTC)
Message
Larkin said:
I'm a little concerned by the exits that do not connect on the map window, hoping that will be fixed eventually.


Where exit lines don't meet up, they're not supposed to: those exits don't go to the same rooms. The map is drawn with all exits the same length, so it's very easy and common for rooms to overlap. The closest room is drawn first, since it's a breadth-first algorithm, and any rooms that would also occupy that same spot aren't drawn.

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
[Go to top] top

Posted by Larkin   (278 posts)  [Biography] bio
Date Reply #7 on Fri 12 Mar 2010 04:33 PM (UTC)
Message
My mapper allows for custom lengths on exit lines, to draw the irregular layouts better.

Should also consider one-way exits and special exits (enter portal, transverse ethereal, etc).
[Go to top] top

Posted by Twisol   USA  (2,257 posts)  [Biography] bio
Date Reply #8 on Fri 12 Mar 2010 04:43 PM (UTC)
Message
Larkin said:
My mapper allows for custom lengths on exit lines, to draw the irregular layouts better.

Something I suggested too. What we've got now is still phenomenal though.

'Soludra' on Achaea

Blog: http://jonathan.com/
GitHub: http://github.com/Twisol
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #9 on Fri 12 Mar 2010 07:28 PM (UTC)
Message
Garrion said:

I love the look of this system. I play a Mud that does not have unique room names or numbers. I am guessing this system won't work on Mud's like this...


I presume you mean you aren't sure which room you are in? The rooms would have to be unique internally.

You could ask nicely if you can find out the unique room number (eg. on a MUSH you could do that). Failing that, you may be able to do something like hash:

<room title> + <room description> + <room exits line>

and have something that usually would be unique. Then the mapper could be made to work.

Otherwise you might point out to the MUD admins that if they aren't prepared to help you get your mapper to work, there are other MUDs around that are. :)

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #10 on Fri 12 Mar 2010 07:31 PM (UTC)
Message
Larkin said:

I'm a little concerned by the exits that do not connect on the map window, hoping that will be fixed eventually.


As Twisol said, that is intentional. If you get close enough, the lines join. This is one of the problems of mapping 3D space onto a 2D screen (and indeed this has always been a problem for map-makers).

The unjoined lines are a hint that if you go closer there are rooms to be explored there.

Larkin said:

I'll be glad to provide you with a copy of my own mapper script for Lusternia, based on the MudBot module, as it has some nice features for locating people on the map, auto-locating you when you get lost or teleport, and things like that...


This mapper assumes you know where you are (ie. by the MUD telling you a room number/code).

However I am always open to suggestions for improvements.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #11 on Fri 12 Mar 2010 07:33 PM (UTC)
Message
Larkin said:

My mapper allows for custom lengths on exit lines, to draw the irregular layouts better.

Should also consider one-way exits and special exits (enter portal, transverse ethereal, etc).


This mapper regenerates the map every time you move from the raw data (ie. current room and its exits). There isn't a "map file" on disk that you can edit and lengthen lines. Having said that I was thinking it could auto-join small gaps.

It currently handles one-way exits by drawing a small arrow.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Reply #12 on Fri 12 Mar 2010 07:39 PM (UTC)
Message
Following on from a comment by Twisol before, the mapper now has a "mapper goto x" command. This assumes you know a particular room number, and just want to go there (from wherever you happen to be). For example, in a city you may want to go the bank, or your guild HQ or something.

So this just locates the quickest path to that room, and automatically speedwalks you there.

This would be a handy thing to bind to a hotkey for a place you need to visit often (eg. for a quest).

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Larkin   (278 posts)  [Biography] bio
Date Reply #13 on Fri 12 Mar 2010 07:46 PM (UTC)
Message
If you haven't looked at the MudBot mapper module, I seriously recommend giving it a good scan. It's a very well built, albeit a bit confusing, mapper.

You have the database, and MudBot has a plain text file, so the two are similar in that there is a data source from which you start. I'll build a translator from MudBot to SQLite, if the feature set in this new mapper comes together nicely. :)

The plain text format is straightforward and flexible enough that it's incredibly useful. For example:
AREA
Name: Serenwilde Forest.

ROOM v1
Name: Atop an oak.
Type: trees
E: in 438
E: down 100
E: west 2


Defines an area, followed by a room in that area. The room has a vnum (defined by the mapper, not the game, but that can change with ATCP codes now), name, terrain type, and a few exits to other vnums.

A detected exit to the north that isn't yet linked to another room:
DE: north


A detected exit that is locked to the down:
DEL: down


An exit that looks better when the length is doubled (length of 0 is the default), used for rendering ASCII maps:
E: southeast 275
EL: southeast 1


A special exit triggered by a special command and followed by a special message (the 9 is an alias for 'up' in this case, meaning you can send 'up' and the mapper sends 'transverse ethereal' instead):
SPE: 540 9 "transverse ethereal" "You place your hands on the Moonhart Mother Tree..."


That's most of the useful stuff, but there are a few more things like joining two areas together via an exit or substituting a cardinal direction to be rendered for some non-standard exit ('in' can become 'north' on a particular exit on the map).

When I re-wrote the MudBot mapper in Lua, I used Ked's pathfinder algorithm because the MudBot code confused me there. I understand what MudBot is doing but not exactly how. He stores the path tree in the map rooms, such that if you're running along a path and something pushes you into a nearby room, it knows the path from that room already and can keep going toward your destination with no additional effort. Very slick, really.
[Go to top] top

Posted by David Haley   USA  (3,881 posts)  [Biography] bio
Date Reply #14 on Fri 12 Mar 2010 08:26 PM (UTC)
Message
Nick Gammon said:
You could ask nicely if you can find out the unique room number (eg. on a MUSH you could do that).

For whatever reason, many MUD admins have a gut reaction against giving out this data. I think they feel like it's giving information to players that they can exploit. Usually this is a somewhat irrational reaction, IMHO, however the one place it is justified is when you want a maze type of area where rooms intentionally look very similar, and exits aren't necessarily as expected. If you had a mapper program, the whole purpose of the maze would disappear. Now, you might argue that such mazes shouldn't exist, but, well...

David Haley aka Ksilyan
Head Programmer,
Legends of the Darkstone

http://david.the-haleys.org
[Go to top] top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.


674,835 views.

This is page 1, subject is 17 pages long: 1 2  3  4  5  6  7  8  9  10  11  12  13  14  15  16  17  [Next page]

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page

Go to topic:           Search the forum


[Go to top] top

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at HostDash]