Difference between revisions of "Manual:Mudlet Packages"
Line 1: | Line 1: | ||
{{TOC right}} | {{TOC right}} | ||
= What is a Mudlet package = | = What is a Mudlet package = | ||
− | It's a | + | 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). | |
− | + | = 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. 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. | |
= How to install a Mudlet package = | = How to install a Mudlet package = | ||
− | == | + | == as a package == |
Toolbox→Package Manager will open the window where you can 'Install' to install a package. The package will then get merged into the Mudlet profile and can be deleted. | Toolbox→Package Manager will open the window where you can 'Install' to install a package. The package will then get merged into the Mudlet profile and can be deleted. | ||
− | + | == as a module == | |
− | Toolbox→Module Manager | + | Use Toolbox→Module Manager to install a module. |
− | |||
− | |||
− | + | == as a one-liner == | |
As a script writer, you can also allow people to just copy/paste a command into Mudlet to install your package - super easy. Here's a demo, paste this into Mudlet: | As a script writer, you can also allow people to just copy/paste a command into Mudlet to install your package - super easy. Here's a demo, paste this into Mudlet: | ||
Revision as of 12:48, 28 August 2018
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).
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. 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.
How to install a Mudlet package
as a package
Toolbox→Package Manager will open the window where you can 'Install' to install a package. The package will then get merged into the Mudlet profile and can be deleted.
as a module
Use Toolbox→Module Manager to install a module.
as a one-liner
As a script writer, you can also allow people to just copy/paste a command into Mudlet to install your package - super easy. Here's a demo, paste this into Mudlet:
lua function d(a,b)if not b:find("oci",1,true)then return end installPackage(b)os.remove(b)cecho("<lime_green>Package installed!\n")end registerAnonymousEventHandler("sysDownloadDone","d")downloadFile(getMudletHomeDir().."/oci.mpackage","http://www.mudlet.org/wp-content/files/one-click-install-demo.mpackage")
To get such a line for your script, do the following:
1) Copy/paste code below to https://mothereff.in/lua-minifier
local URL = "http://www.mudlet.org/wp-content/files/one-click-install-demo.mpackage"
function d(_, f)
if not f:find("oci", 1, true) then return end
installPackage(f)
os.remove(f)
cecho("<lime_green>Package installed!\n")
end
registerAnonymousEventHandler("sysDownloadDone", "d")
downloadFile(getMudletHomeDir()..(URL:ends("xml") and "/oci.xml" or "/oci.zip"), URL)
2) replace the URL (the http://www.mudlet.org/wp-content/files/one-click-install-demo.mpackage
bit) with your .zip, .mpackage, or .xml URL
3) find & replace all semicolons (;) with spaces ( ) in the minified version
4) prefix it with 'lua ' and paste it into Mudlet!
note: requires Mudlet 3.0 to work.
from the MUD
Packages can also be auto-installed from the MUD server via ATCP or GMCP - see ATCP extensions or GMCP extensions for more.
How to create a Mudlet package
Create a 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 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")