Adding your mud to the IRE mapping script

The IRE mapping script is a feature rich and robust Lua script that utilizes available GMCP data to make creating and using maps for any game you're playing with Mudlet much easier. Though it was developed by players of and is principally used for Iron Realms Entertainment's various games, it is possible to add any GMCP capable game to the script and take advantage of the myriad of features it offers. This page will outline the basic steps necessary to do this, though as every game is different, it may not be exhaustive.

Make sure GMCP is enabled and available

Mudlet has enabled GMCP by default since version 3.1, but it can't hurt to double check that it's enabled. Navigate over to 'Options -> Preferences -> General -> Game Protocols' and make sure the 'Enable GMCP' box is checked, and that lua gmcp in the input line shows you GMCP content. Of course, this doesn't help if your game doesn't offer GMCP at all - if it does, there's likely an in game help file about it that will offer you more information. If not, maybe your game admin is open to adding it? You can direct them here to learn more.

What does the script need?

Besides the specifics detailed below that will need to be added to the script for each game, the script requires specific GMCP data to function. It is entirely possible to add workarounds to the script, but you'll find adding your game easier if the GMCP formatting in your game already matches the formatting that the script looks for. Generally, the formatting is 'gmcp.Category.Subcategory.data'.

gmcp.Room - main grouping for rooms. This is where it figures out what a room is.
gmcp.Room.Info - Room information subcategory. Contains a table of data points.
gmcp.Room.Info.area - The area name that the room is in. Used to set area automatically as you map.
gmcp.Room.Info.name - The name of the room you're in. Sets the room name as it creates a new room.
gmcp.Room.Info.environment - The environment of the room. Sets individual environments, allowing for special interactions (such as swimming) as well as coloring the map.
gmcp.Room.Info.num - the unique number of the room. This is used to differentiate rooms that are otherwise similar in name or exits.
gmcp.Room.Info.exits - The exits that connect to this room, should include both the direction and the number of the room. Automatically tries to link exits to existing rooms.

There are many other things you might want to track via GMCP - and for some games, the script already does, like whether or not a room is indoors. But the above data is the absolute minimum required to use the script.

Getting started

To get started, you'll need to create a GitHub account. Once you've done so, navigate over to the mapping script page and fork it into your own repository. Download your repository, saving it somewhere you'll remember. Open your Mudlet profile for your game, and use the Module Manager to install the 'mudlet-mapper.xml' file in your repository directory, making sure to click the 'Sync' option. Now, when you save the Mudlet profile you've installed that module to, it'll save the changes to your repository - meaning you can commit any changes directly to your repository. At the end of this journey, you can choose to submit your changes to the master branch as a pull request, and have your repository merged with the main script - so that anyone who plays your game can use the script!

Adding your game to the script

Now that you've got the script installed and synced, you can add your game by following the steps below.

Step one: Create necessary triggers.

• Create a trigger group for your game. Navigate to 'Triggers -> mudlet-mapper -> Mudlet Mapper' and click 'Add Group'. Name your new group after your game.
• Create a login trigger for your game inside your new trigger group. Click 'Add Item', name your new item 'Login' and choose part of the splash screen for your game that is reasonably unique. For example, most games will say 'Welcome to [game name].' which is great! You can use any type of match you want, as long as it's unique to your game. In the script box, type the following:

raiseEvent("mmp logged in", "YourGame")
mmp.game = "yourgame"

So it will look something like this:

A login trigger for Asteria.

Step two: Create necessary scripts.

• Create an environment data script for your game. This will tell the script what color to make a square on your map that is a certain environment, as well as telling the script certain things in advance, such as that an environment will require you to move in a specific way, like swimming. Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper - Game-specific' and click 'Add Item'. Name the new script item after your game and save it.
• Create a script named 'register_yourgames_envdata'. Save this item, and then use your mouse to drag it into the script you just made named after your game, so it looks like this:

A nested script example.

• In the script editor for this script, mouse over to the 'Add User Event Handler' command line, and type 'mmp logged in' and press the '+' key. This will cause this script to be run when the login trigger we made previously fires.

• In the script box below, you'll need to define the environments of your game. If you want, you can probably just copy one of the existing scripts and edit its name and environments to match your game. For a more detailed approach that will let you set individual colors to go with the environment codes you assign, see the script for Asteria.

Step three: Add your game to existing scripts.

Some parts of the mapping script will need to be edited to recognize your game, or work in a way that is unique to your game. This section seeks to help with that, though it's unlikely to be exhaustive.

User Configurable Settings

This script has a number of game specific toggles that a user can activate or deactivate as they wish, displayed and configured with the 'mconfig' alias. You can add your own specific settings that your game might have, or make sure that your users can use existing general settings. To do so, navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Load Settings'.

You'll need to decide for yourself what you'll want to add or edit here, but simply follow the formatting of the other entries in the script to add your own items.

Crowd Sourced Mapping

By default, you'll be able to use your own local map file, or any that you can download from another user. Some muds (like those from Iron Realms) even offer a map themselves. However, if you wish to set up a crowd map repository for users to contribute to, that's possible. There's a helpful template over on the IRE Mapping GitHub, even. The script already comes with an option to enable or disable use of a crowd sourced map. Assuming you've got a website that you can host a map file on, you can use this to automatically distribute updates to those who enable the setting on your game. To make use of it though, you'll need to add some things:

• Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Load Settings' and look for 'private_settings["crowdmap"] - copying the existing formatting, add your game to the end of the line.

• Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Utilities -> mconfig settings functions' and look for 'mmp.changeMapSource' and copy existing formatting to add your game to the check for crowdsourced map availability.

• Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Check for map updates -> Check for updates' and look for 'mmp.settings.crowdmap' and copy existing formatting to add your game.

• Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Check for map updates -> Check for updates' and look for 'mmp.retrievechangelog' and copy existing formatting to add your game.

• Navigate to 'Scripts -> mudlet-mapper -> Mudlet Mapper -> Check for map updates -> Check for updates' and look for 'mmp.downloadcrowdmap' and copy existing formatting to add your game.

All done, everything seems to work, now what?

Submit your changes as a pull request to the master branch of the mapping script, so that everyone can benefit from your hard work! Well done!

Help, I did everything and it still doesn't work?!

If you've followed the above steps, and can verify that the individual pieces are working - no errors in the error log, no typos, etc - then it's probable your game might need a special workaround for a specific aspect of the script. For example, Asteria doesn't use the common syntax 'open door <dir>', but rather uses 'open <dir>' - which meant that to add Asteria to the script, I had to add an additional check to that part of the script that sends a different command if the script sees that I'm playing Asteria.

If you're hitting a similar snag, head over to the Mudlet Discord for some help!