Manual:Mudlet Packages

What is a Mudlet package

It's a zip file that ends with .mpackage or .zip that contains xml files to import along with any resources a package might have (images, sounds and etc), or simply an .xml file on its own. Packages can be installed / uninstalled via a window in Mudlet.

You'll see packages represented in brown in the script editor everywhere - triggers, aliases, etc. All items of a package have to go into a package folder that they belong in - so the user can know which package do items belong to, and modify the package for their needs (if it didn't have a folder, then you wouldn't be able to 'add' anything to a package).

Where to find Mudlet packages

Check out the Scripts & Packages section on Mudlet forums for an excellent selection of Mudlet packages. Those listings are also being transferred over to the Mudlet Package Listing.

Some Mudlet packages may also be exclusively available on your own game-specific website or forums, so make sure to check out what your game has to offer as well.

What is a Mudlet module

It's the same thing as a Mudlet package - the only difference is how you import it: via the Module manager instead of the Package manager, and what happens after: Mudlet will save the module back to the original file instead of the profile save file. This means the original xml or mpackage (in Mudlet 4.14+) will automatically get updated. Really useful if you're writing Mudlet code to share with others - you won't have to ever manually export it again, Mudlet will do it automatically for you! You can version your modules using Git using this way.

You can also share a module across several profiles and automatically keep it in sync by installing the module in the relevant profiles and ticking the "sync" option in all of them.

If you'd like your module to be loaded before all the scripts in a Mudlet profile, you can do that with the -1 module priority.

How to install a Mudlet package

as a package

Drag and drop the link to the package into Mudlet (4.11+) or the the package file itself (as of 4.8+) and it'll get installed. The package will then get merged into the Mudlet profile and the original file can be deleted.

Alternatively, Toolbox→Package Manager will open the window where you can hit 'Install'.

as a one-liner

In the command line as a package:

lua installPackage("https://<online package location>")

In the command line as a module:

lua installModule("https://<online package location>")

as a module

Use Toolbox→Module Manager to install a module.

from the game

Packages can also be auto-installed from the MUD server via ATCP or GMCP - see ATCP extensions or GMCP extensions for more.

Module best practices

Are you making a Mudlet package? We keep a list of some best practices we've accumulated over the years at Manual:Best_Practices#Package_and_Module_best_practices

There are some decisions you can make that are outside of best practices, but will influence things:

• write all code inside Mudlet, or outside Mudlet in .lua files?
  • If you want more contributors you may find it better to use the built in Mudlet editor, as more of the Mudlet userbase is familiar with it.
  • If you want the power of a full IDE or dislike XML diffs in your SCM, then use the latter, see muddler, an unofficial tool for Mudlet packages.

Create a Mudlet package with Mudlet Profile Exporter

Mudlet provides an export dialog for saving a subset of a profile's settings and configuration to a file.

Exported settings are saved into a package that can be imported using Package Manager > Install new package.

Package information

Each new package requires a name or use the dropdown menu to update a currently installed package. Select the profile configuration and definitions to be exported using the interface. For simple exports, this information is enough to create a file.

To build a Mudlet package following best practices, use the Package details by pressing add icon, description, and more to define additional metadata and provide information to Mudlet users that choose to import your package.

Package optional details

The optional details allow setting:

• Author information

• An icon, 512x512 recommended

• A description for those interested in learning more, and documenting any features or a short changelog

• A version number

You can use Github-flavoured markdown in the package description to give a nice presentation for the player. For inspiration on creating good quality descriptions, check out packages here and here.

External data, dependencies

If your package requires other Mudlet packages, add them under the Required packages dropdown. For example creating a set of custom triggers for a game to use with generic_mapper.

Packages that reference local files such as in the Including images, sounds, and other files section below will need to declare them in this section, to export them for reuse. Without these files the package may work locally but not on another's computer.

To remove an included asset, select it from the list and use backspace (fn + delete on macOS) to remove it.

NOTE: To remove a dependency that has already been selected and added, use CTRL+Delete (Linux/Windows) or FN+Backspace (MacOS).

Save exported profile

Mudlet will put the exported package on the current user's desktop by default. Use Select export location to pick a different destination.

Export to write the package, Close to exit

Create a Mudlet package by hand

Alternatively, you can create a package by hand - it's zip file that ends with either .mpackage (preferred) or .zip. Include all xml's that you'd like to be installed in the top level folder of the package - that is, don't have them within a folder in the archive - just have them be upfront.

Naming the package

Add a file at the top level of the package (so not inside any folders in the package) called config.lua that has the following line to name your package:

mpackage = "<name of your package>"

That's it. If you don't include config.lua, Mudlet will then deduce the package name from the file name.

Including images, sounds, and other files

If you'd like to include other folders or files in the package, you can - they will be copied into getMudletHomeDir().."/"..packagename upon installation, so your scripts can use them. Since Mudlet 3.10 you can include font files (.otf or .ttf) and they will be automatically available for your scripts to use.

For example, if your package is called "sipper" and you have health.png as an image in it, you can place on a label like so:

-- you don't have to worry about \ versus / for file paths - use / everywhere, Lua will make it work on Windows fine

setBackgroundImage("my health label", getMudletHomeDir().."/sipper/health.png")

Install the one-liner package demo above for an example of how to make use of images in packages.

Using .lua files

As of Mudlet 3.6.2 you can require "myfile" to load myfile.lua from the package folder.

As an example, if you have your package sipper, using a custom echo function named sipperecho defined in customFunctions.lua you can

require "sipper.customFunctions"

sipperecho("I work")

Alternatively you can rename customFunctions.lua to init.lua, this will allow you to require "<name of your package>" and

require "sipper"

sipperecho("I work")