https://wiki.mudlet.org/api.php?action=feedcontributions&user=Vadi&feedformat=atomMudlet - User contributions [en]2024-03-28T09:23:05ZUser contributionsMediaWiki 1.35.0https://wiki.mudlet.org/index.php?title=Manual:Mapper_Functions&diff=21520Manual:Mapper Functions2024-03-22T05:32:10Z<p>Vadi: /* setRoomChar */ remove duplicate information</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions that manipulate the mapper and its related features.}}<br />
= Mapper Functions =<br />
These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the game you're playing. For a collection of pre-made scripts and general mapper talk, visit the [http://forums.mudlet.org/viewforum.php?f=13 mapper section] of the forums.<br />
<br />
To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:<br />
<syntaxhighlight lang="lua"><br />
mudlet = mudlet or {}; mudlet.mapper_script = true<br />
</syntaxhighlight><br />
<br />
==addAreaName==<br />
;areaID = addAreaName(areaName)<br />
<br />
:Adds a new area name and returns the new (positive) area ID for the new name. If the name already exists, older versions of Mudlet returned -1 though since 3.0 the code will return ''nil'' and an error message.<br />
: See also: [[#deleteArea|deleteArea()]], [[#addRoom|addRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local newId, err = addAreaName("My House")<br />
<br />
if newId == nil or newId < 1 or err then<br />
echo("That area name could not be added - error is: ".. err.."\n")<br />
else<br />
cecho("<green>Created new area with the ID of "..newId..".\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==addCustomLine==<br />
;addCustomLine(roomID, id_to, direction, style, color, arrow)<br />
: See also: [[#getCustomLines|getCustomLines()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to attach the custom line to.<br />
* ''id_to:''<br />
: EITHER: a room Id number, of a room on same area who's x and y coordinates are used as the other end of a SINGLE segment custom line (it does NOT imply that is what the exit it represent goes to, just the location of the end of the line);<br />
: OR: a table of sets of THREE (x,y and z) coordinates in that order, x and y can be decimals, z is an integer ('''and must be present and be the same for all points on the line''', though it is irrelevant to what is produced as the line is drawn on the same z-coordinate as the room that the line is attached to!)<br />
* ''direction:'' a string to associate the line with a valid exit direction, "n", "ne", "e", "se", "s", "sw", "w", "nw", "up", "down", "in" or "out" or a special exit (before Mudlet 3.17 this was case-sensitive and cardinal directions had to be uppercase).<br />
* ''style:'' a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.<br />
* ''color:'' a table of three integers between 0 and 255 as the custom line color as the red, green and blue components in that order.<br />
* ''arrow:'' a boolean which if true will set the custom line to have an arrow on the end of the last segment.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- create a line from roomid 1 to roomid 2<br />
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)<br />
<br />
addCustomLine(1, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
</syntaxhighlight><br />
<br />
A bigger example that'll create a new area and the room in it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local areaid = addAreaName("my first area")<br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
setRoomArea(newroomid, "my first area")<br />
setRoomCoordinates(newroomid, 0, 0, 0)<br />
<br />
local otherroomid = createRoomID()<br />
addRoom(otherroomid)<br />
setRoomArea(otherroomid, "my first area")<br />
setRoomCoordinates(otherroomid, 0, 5, 0)<br />
<br />
addSpecialExit(newroomid, otherroomid, "climb Rope")<br />
addCustomLine(newroomid, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
<br />
centerview(newroomid)<br />
</syntaxhighlight><br />
<br />
==addMapEvent==<br />
;addMapEvent(uniquename, event name, parent, display name, arguments)<br />
<br />
:Adds a new entry to an existing mapper right-click entry. You can add one with addMapMenu. If there is no display name, it will default to the unique name (which otherwise isn't shown and is just used to differentiate this entry from others). ''event name'' is the Mudlet event that will be called when this is clicked on, and ''arguments'' will be passed to the handler function.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn") <br />
</syntaxhighlight><br />
The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.<br />
<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Room type")<br />
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")<br />
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")<br />
<br />
function onMapMarkSelectedRooms(event, markRoomType)<br />
local selectedRooms = getMapSelection()["rooms"]<br />
for i, val in ipairs(selectedRooms) do<br />
if markRoomType == "markRoomsAsDeathTrap" then<br />
local r, g, b = unpack(color_table.black)<br />
--death trap<br />
setRoomEnv(val, 300)<br />
--death traps Env<br />
setCustomEnvColor(300, r, g, b, 255)<br />
setRoomChar(val, "☠️")<br />
lockRoom(val, true)<br />
elseif markRoomType == "markRoomsAsOneRoom" then<br />
local r, g, b = unpack(color_table.LightCoral)<br />
--single-pass<br />
setRoomEnv(val, 301)<br />
--one room Env<br />
setCustomEnvColor(301, r, g, b, 255)<br />
setRoomChar(val, "🚹")<br />
end<br />
end<br />
updateMap()<br />
end<br />
<br />
registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")<br />
</syntaxhighlight><br />
This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"<br />
<br />
==addMapMenu==<br />
;addMapMenu(uniquename, parent, display name)<br />
<br />
:Adds a new submenu to the right-click menu that opens when you right-click on the mapper. You can then add more submenus to it, or add entries with [[#addMapEvent|addMapEvent()]].<br />
: See also: [[#addMapEvent|addMapEvent()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will create a menu named: Favorites.<br />
addMapMenu("Favorites")<br />
<br />
-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.<br />
addMapMenu("Favorites1234343", "Favorites", "More Favorites") <br />
</syntaxhighlight><br />
<br />
==addRoom==<br />
;addRoom(roomID)<br />
<br />
:Creates a new room with the given ID, returns true if the room was successfully created. <br />
<br />
{{note}} If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with [[#createRoomID|createRoomID()]] and associating your room IDs with Mudlets via [[#setRoomIDbyHash|setRoomIDbyHash()]] and [[#getRoomIDbyHash|getRoomIDbyHash()]]. The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge.<br />
{{note}} Creating your own mapping script? Check out more [[Manual:Mapper#Making_your_own_mapping_script|information here]].<br />
<br />
: See also: [[#createRoomID|createRoomID()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
</syntaxhighlight><br />
<br />
==addSpecialExit==<br />
;addSpecialExit(roomIDFrom, roomIDTo, moveCommand)<br />
<br />
:Creates a one-way from one room to another, that will use the given command for going through them.<br />
<br />
: See also: [[#clearSpecialExits|clearSpecialExits()]], [[#removeSpecialExit|removeSpecialExit()]], [[#setExit|setExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command<br />
addSpecialExit(1, 2, "pull rope")<br />
</syntaxhighlight><br />
<br />
Example in an alias:<br />
<syntaxhighlight lang="lua"><br />
-- sample alias pattern: ^spe (\d+) (.*?)$<br />
-- currentroom is your current room ID in this example<br />
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])<br />
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])<br />
centerview(currentroom)<br />
</syntaxhighlight><br />
<br />
==auditAreas==<br />
;auditAreas()<br />
<br />
: Initiates a consistency check on the whole map: All rooms, areas, and their composition. This is also done automatically whenever you first open your map, so probably seldom necessary to do manually. Will output findings to screen and/or logfile for later review.<br />
<br />
: See also: [[#saveMap|saveMap()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
==centerview==<br />
;centerview (roomID)<br />
<br />
:Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.<br />
<br />
: See also: [[#getPlayerRoom|getPlayerRoom()]], [[#updateMap|updateMap()]]<br />
<br />
==clearAreaUserData==<br />
;clearAreaUserData(areaID)<br />
<br />
; Parameter<br />
* areaID - ID number for area to clear.<br />
<br />
:Clears all user data from a given area. Note that this will not touch the room user data.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#clearRoomUserData|clearRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearAreaUserData(34))<br />
-- I did have data in that area, so it returns:<br />
true<br />
<br />
display(clearAreaUserData(34))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearAreaUserDataItem==<br />
;clearAreaUserDataItem(areaID, key)<br />
<br />
:Removes the specific key and value from the user data from a given area.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#clearAreaUserData|clearAreaUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
true<br />
<br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapSelection==<br />
;clearMapSelection()<br />
<br />
:Clears any selected rooms from the map (i.e. they are highlighted in orange).<br />
<br />
:Returns true if rooms are successfully cleared, false if nothing selected or cleared.<br />
<br />
: See also [[#getMapSelection|getMapSelection()]]<br />
<br />
==clearMapUserData==<br />
;clearMapUserData()<br />
<br />
:Clears all user data stored for the map itself. Note that this will not touch the area or room user data.<br />
<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserData|clearAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearMapUserData())<br />
-- I did have user data stored for the map, so it returns:<br />
true<br />
<br />
display(clearMapUserData())<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapUserDataItem==<br />
;clearMapUserDataItem(mapID, key)<br />
<br />
:Removes the specific key and value from the user data from the map user data.<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearMapUserData|clearMapUserData()]], [[#clearAreaRoomUserData|clearAreaRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
last_modified = "1483228799"<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
true<br />
<br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearRoomUserData==<br />
;clearRoomUserData(roomID)<br />
<br />
:Clears all user data from a given room.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{note}} Returns a boolean true if any data was removed from the specified room and false if there was nothing to erase since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearRoomUserData(3441))<br />
-- I did have data in that room, so it returns:<br />
true<br />
<br />
display(clearRoomUserData(3441))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearRoomUserDataItem==<br />
;clearRoomUserDataItem(roomID, key)<br />
<br />
:Removes the specific key and value from the user data from a given room.<br />
:Returns a boolean true if data was found against the give key in the user data for the given room and it is removed, will return false if exact key not present in the data. Returns nil if the room for the roomID not found.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
true<br />
<br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearSpecialExits==<br />
;clearSpecialExits(roomID) <br />
<br />
:Removes all special exits from a room.<br />
: See also: [[#addSpecialExit|addSpecialExit()]], [[#removeSpecialExit|removeSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
clearSpecialExits(1337)<br />
<br />
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example<br />
echo("All special exits successfully cleared from 1337.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==closeMapWidget==<br />
;closeMapWidget()<br />
:closes (hides) the map window (similar to clicking on the map icon)<br />
<br />
{{MudletVersion|4.7}}<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
==connectExitStub==<br />
;connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])<br />
<br />
:Connects existing rooms with matching exit stubs. If you only give it a roomID and a direction, it'll work out which room should be linked to it that has an appropriate opposite exit stub and is located in the right direction. You can also just specify from and to room IDs, and it'll smartly use the right direction to link in. Lastly, you can specify all three arguments - fromID, toID and the direction (in that order) if you'd like to be explicit, or use [[#setExit|setExit()]] for the same effect.<br />
<br />
;Parameters<br />
* ''fromID:''<br />
: Room ID to set the exit stub in.<br />
* ''direction:''<br />
: You can either specify the direction to link the room in, and/or a specific room ID (see below). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
* ''toID:''<br />
: The room ID to link this room to. If you don't specify it, the mapper will work out which room should be logically linked.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- try and connect all stubs that are in a room<br />
local stubs = getExitStubs(roomID)<br />
if stubs then<br />
for i,v in pairs(stubs) do<br />
connectExitStub(roomID, v)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==createMapLabel==<br />
;labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])<br />
<br />
:Creates a text label on the map at given coordinates, with the given background and foreground colors. It can go above or below the rooms, scale with zoom or stay a static size. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a script can reduce the size of the saved map somewhat. It returns a label ID that you can use later for deleting it.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
<br />
: See also: [[#getMapLabel|getMapLabel()]], [[#getMapLabels|getMapLabels()]], [[#deleteMapLabel|deleteMapLabel]], [[#createMapImageLabel|createMapImageLabel()]]<br />
<br />
{{note}} Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID where to put the label.<br />
* ''text:''<br />
: The text to put into the label. To get a multiline text label add a '\n' between the lines.<br />
* ''posX, posY, posZ:''<br />
: Position of the label in (floating point numbers) room coordinates.<br />
* ''fgRed, fgGreen, fgBlue:''<br />
: Foreground color or text color of the label.<br />
* ''bgRed, bgGreen, bgBlue:''<br />
: Background color of the label.<br />
* ''zoom:''<br />
: (optional) Zoom factor of the label if noScaling is false. Higher zoom will give higher resolution of the text and smaller size of the label. Default is 30.0.<br />
* ''fontSize:''<br />
: (optional, but needed if zoom is provided) Size of the font of the text. Default is 50.<br />
* ''showOnTop:''<br />
: (optional) If true the label will be drawn on top of the rooms and if it is false the label will be drawn as a background, defaults to true if not given.<br />
* ''noScaling:''<br />
: (optional) If true the label will have the same size when you zoom in and out in the mapper, If it is false the label will scale when you zoom the mapper, defaults to true if not given.<br />
* ''fontName:''<br />
: (optional) font name to use.<br />
* ''foregroundTransparency''<br />
: (optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.<br />
* ''backgroundTransparency''<br />
: (optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.<br />
* ''temporary''<br />
: (optional, from Mudlet version 4.17.0) if true does not save the image that the label makes in map save files, defaults to false if not given, or for prior versions of Mudlet.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area<br />
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB<br />
-- zoom is only relevant when when you're using a label of a static size, so we use 0<br />
-- and we use a font size of 20 for our label, which is a small medium compared to the map<br />
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)<br />
<br />
-- to create a multi line text label we add '\n' between lines<br />
-- the position is placed somewhat to the northeast of the center of the map<br />
-- this label will be scaled as you zoom the map.<br />
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)<br />
<br />
local x,y,z = getRoomCoordinates(getPlayerRoom())<br />
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)<br />
</syntaxhighlight><br />
<br />
==createMapImageLabel==<br />
;labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])<br />
<br />
:Creates an image label on the map at the given coordinates, with the given dimensions and zoom. You might find the default room and image size correlation to be too big - try reducing the width and height of the image then, while also zooming in the same amount. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a external file available when the map file is loaded, can avoid expanding the size of the saved map considerably.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
: See also: [[#createMapLabel|createMapLabel]], [[#deleteMapLabel|deleteMapLabel]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- 138 is our pretend area ID<br />
-- next, inside [[]]'s, is the exact location of our image<br />
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map<br />
-- 482 is the width of the image - we divide it by 100 to scale it down, and then we'll zoom it by 100 - making the image take up about 4 rooms in width then<br />
-- 555 is the original height of the image<br />
-- 100 is how much we zoom it by, 1 would be no zoom<br />
-- false to make it go below our rooms<br />
-- (from 4.17.0) true to not save the label's image in the map file afterwards<br />
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)<br />
</syntaxhighlight><br />
<br />
==createMapper==<br />
;createMapper([name of userwindow], x, y, width, height)<br />
<br />
:Creates a miniconsole window for the mapper to render in, the with the given dimensions. You can only create one mapper at a time, and it is not currently possible to have a label on or under the mapper - otherwise, clicks won't register.<br />
<br />
{{note}} ''name of userwindow'' available in Mudlet 4.6.1+<br />
<br />
{{Note}} If this command is ''not'' used then clicking on the Main Toolbar's '''Map''' button will create a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Map''' button will toggle between showing and hiding the map whether it was created using the ''createMapper'' function or as a dock-able widget.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet<br />
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- another example:<br />
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})<br />
<br />
local mapper = Geyser.Mapper:new({<br />
name = "mapper",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, main)<br />
</syntaxhighlight><br />
<br />
==createRoomID==<br />
;usableId = createRoomID([minimumStartingRoomId])<br />
<br />
:Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs. <br />
<br />
;Parameters<br />
* ''minimumStartingRoomId'' (optional, available in Mudlet 3.0+):<br />
: If provided, specifies a roomID to start searching for an empty one at, instead of 1. Useful if you'd like to ensure certain areas have specific room number ranges, for example. If you you're working with a huge map, provide the last used room ID to this function for an available roomID to be found a lot quicker.<br />
<br />
: See also: [[#addRoom|addRoom()]]<br />
<br />
==deleteArea==<br />
;deleteArea(areaID or areaName)<br />
<br />
:Deletes the given area and all rooms in it. Returns ''true'' on success or ''nil'' + ''error message'' otherwise.<br />
: See also: [[#addAreaName|addAreaName()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to delete, or:<br />
* ''areaName'' (available in Mudlet 3.0+):<br />
: Area name to delete.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete by areaID<br />
deleteArea(23)<br />
-- or since Mudlet 3.0, by area name<br />
deleteArea("Big city")<br />
</syntaxhighlight><br />
<br />
==deleteMap==<br />
;deleteMap()<br />
<br />
Deletes the entire map. This may be useful whilst initially setting up a mapper package for a new Game to clear faulty map data generated up to this point.<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
{{MudletVersion|4.14.0}}<br />
<br />
;Returns<br />
:''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result - which will be the "blank" screen with a warning message of the form ''"No rooms in the map - load another one, or start mapping from scratch to begin."''<br />
<br />
{{note}} Prior to the introduction of this function, the recommended method to achieve the same result was to use [[#loadMap|loadMap()]] with a non-existent file-name, such as ''"_"'' however that would also cause an ''"[ ERROR ]"'' type message to appear on the profile's main console.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMap()<br />
</syntaxhighlight><br />
<br />
==deleteMapLabel==<br />
;deleteMapLabel(areaID, labelID)<br />
<br />
:Deletes a map label from a specific area.<br />
: See also: [[#createMapLabel|createMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMapLabel(50, 1)<br />
</syntaxhighlight><br />
<br />
==deleteRoom==<br />
;deleteRoom(roomID)<br />
<br />
:Deletes an individual room, and unlinks all exits leading to and from it.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteRoom(335)<br />
</syntaxhighlight><br />
<br />
==disableMapInfo==<br />
;disableMapInfo(label)<br />
<br />
Disable the particular map info - same as toggling off checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be disabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==enableMapInfo==<br />
;enableMapInfo(label)<br />
<br />
Enable the particular map info - same as toggling on checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be enabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#disableMapInfo|disableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==getAllAreaUserData==<br />
;dataTable = getAllAreaUserData(areaID)<br />
<br />
:Returns all the user data items stored in the given area ID; will return an empty table if there is no data stored or nil if there is no such area with that ID.<br />
<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
--might result in:--<br />
{<br />
country = "Andor",<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllMapUserData==<br />
;dataTable = getAllMapUserData()<br />
<br />
:Returns all the user data items stored at the map level; will return an empty table if there is no data stored.<br />
<br />
: See also: [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
--might result in:--<br />
{<br />
description = [[This map is about so and so game]],<br />
author = "Bob",<br />
["last updated"] = "December 5, 2020"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllRoomEntrances==<br />
;exitsTable = getAllRoomEntrances(roomID)<br />
<br />
:Returns an indexed list of normal and special exits leading into this room. In case of two-way exits, this'll report exactly the same rooms as [[#getRoomExits|getRoomExits()]], but this function has the ability to pick up one-way exits coming into the room as well.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- print the list of rooms that have exits leading into room 512<br />
for _, roomid in ipairs(getAllRoomEntrances(512)) do <br />
print(roomid)<br />
end<br />
</syntaxhighlight><br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
==getAllRoomUserData==<br />
;dataTable = getAllRoomUserData(roomID)<br />
<br />
:Returns all the user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
;See also: [[#getRoomUserDataKeys|getRoomUserDataKeys()]] - for a related command that only returns the data keys.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
--might result in:--<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
</syntaxhighlight><br />
<br />
==getAreaExits==<br />
;roomTable = getAreaExits(areaID, showExits)<br />
<br />
: Returns a table (indexed or key-value) of the rooms in the given area that have exits leading out to other areas - that is, border rooms.<br />
<br />
;See also: [[#setExit|setExit()]], [[#getRoomExits|getRoomExits()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to list the exits for.<br />
* ''showExits:''<br />
: Boolean argument, if true then the exits that lead out to another area will be listed for each room.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- list all border rooms for area 44:<br />
getAreaExits(44)<br />
<br />
-- returns:<br />
--[[<br />
{<br />
7091,<br />
10659,<br />
11112,<br />
11122,<br />
11133,<br />
11400,<br />
12483,<br />
24012<br />
}<br />
]]<br />
<br />
-- list all border rooms for area 44, and the exits within them that go out to other areas:<br />
getAreaExits(44, true)<br />
--[[<br />
{<br />
[12483] = {<br />
north = 27278<br />
},<br />
[11122] = {<br />
["enter grate"] = 14551<br />
},<br />
[11112] = {<br />
["enter grate"] = 14829<br />
},<br />
[24012] = {<br />
north = 22413<br />
},<br />
[11400] = {<br />
south = 10577<br />
},<br />
[11133] = {<br />
["enter grate"] = 15610<br />
},<br />
[7091] = {<br />
down = 4411<br />
},<br />
[10659] = {<br />
["enter grate"] = 15510<br />
}<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
==getAreaRooms==<br />
;getAreaRooms(area id)<br />
<br />
:Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or ''nil'' if no such area exists. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- using the sample findAreaID() function defined in the getAreaTable() example, <br />
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID<br />
function echoRoomList(areaname)<br />
local id, msg = findAreaID(areaname)<br />
if id then<br />
local roomlist, endresult = getAreaRooms(id), {}<br />
<br />
-- obtain a room list for each of the room IDs we got<br />
for _, id in pairs(roomlist) do<br />
endresult[id] = getRoomName(id)<br />
end<br />
<br />
-- now display something half-decent looking<br />
cecho(string.format(<br />
"List of all rooms in %s (%d):\n", msg, table.size(endresult)))<br />
<br />
for roomid, roomname in pairs(endresult) do<br />
cecho(string.format(<br />
"%6s: %s\n", roomid, roomname))<br />
end<br />
elseif not id and msg then<br />
echo("ID not found; " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTable==<br />
;areaTable = getAreaTable()<br />
<br />
:Returns a key(area name)-value(area id) table with all known areas and their IDs. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
;See also: [[#getAreaTableSwap|getAreaTableSwap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example function that returns the area ID for a given area<br />
<br />
function findAreaID(areaname)<br />
local list = getAreaTable()<br />
<br />
-- iterate over the list of areas, matching them with substring match. <br />
-- if we get match a single area, then return it's ID, otherwise return<br />
-- 'false' and a message that there are than one are matches<br />
local returnid, fullareaname<br />
for area, id in pairs(list) do<br />
if area:find(areaname, 1, true) then<br />
if returnid then return false, "more than one area matches" end<br />
returnid = id; fullareaname = area<br />
end<br />
end<br />
<br />
return returnid, fullareaname<br />
end<br />
<br />
-- sample use:<br />
local id, msg = findAreaID("blahblah")<br />
if id then<br />
echo("Found a matching ID: " .. id)<br />
elseif not id and msg then<br />
echo("ID not found: " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTableSwap==<br />
;areaTable = getAreaTableSwap()<br />
<br />
:Returns a key(area id)-value(area name) table with all known areas and their IDs. Unlike getAreaTable which won't show you all areas with the same name by different IDs, this function will. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
==getAreaUserData==<br />
;dataValue = getAreaUserData(areaID, key)<br />
<br />
:Returns a specific data item stored against the given key for the given area ID number. This is very like the corresponding Room User Data command but intended for per area rather than for per room data (for storage of data relating to the whole map see the corresponding Map User Data commands.) <br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or a Lua ''nil'' and an error message if the key is not present in the Area User Data for the given Area ID. Use [[#setAreaUserData|setAreaUserData()]] function for storing the user data.<br />
<br />
;See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAreaUserData(34, "country"))<br />
-- might produce --<br />
"Andor"<br />
</syntaxhighlight><br />
<br />
==getCustomEnvColorTable==<br />
;envcolors = getCustomEnvColorTable()<br />
<br />
:Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
{<br />
envid1 = {r, g, b, alpha},<br />
envid2 = {r, g, b, alpha}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines==<br />
;lineTable = getCustomLines(roomID)<br />
: See also: [[#addCustomLine|addCustomLine()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Returns a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the custom line details of.<br />
<br />
{{MudletVersion|3.0.}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = {<br />
b = 0,<br />
g = 128,<br />
r = 128<br />
},<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = {<br />
{<br />
y = 9.5,<br />
x = 4.5<br />
},<br />
{<br />
y = 9.5,<br />
x = 6<br />
},<br />
[0] = {<br />
y = 5.5,<br />
x = 4.5<br />
}<br />
}<br />
},<br />
N = {<br />
attributes = {<br />
color = {<br />
b = 255,<br />
g = 255,<br />
r = 0<br />
},<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = {<br />
[0] = {<br />
y = 27,<br />
x = -3<br />
}<br />
}<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines1==<br />
;lineTable = getCustomLines1(roomID)<br />
This is a replacement for ''getCustomLines(...)'' that outputs the tables for the coordinates for the points on the custom line in an order and format that can be fed straight back into an ''addCustomLine(...)'' call; similarly the color parameters are also reported in the correct format to also be reused in the same manner. This function is intended to make it simpler for scripts to manipulate such lines.<br />
:See also: [[Manual:Mapper_Functions#addCustomLine|addCustomLine()]], [[Manual:Mapper_Functions#removeCustomLine|removeCustomLine()]], [[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]<br />
{{MudletVersion| 4.16}}<br />
<br />
;Parameters<br />
* ''roomID:''<br />
:Room ID to return the custom line details of.<br />
<br />
;Returns<br />
:a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines1(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = { 128, 128, 0 },<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } } <br />
},<br />
N = {<br />
attributes = {<br />
color = { 0, 255, 255 },<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = { { -3, 27, 3 } }<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getDoors==<br />
;doors = getDoors(roomID)<br />
<br />
:Returns a key-value table with the cardinal direction as the key and the door value as a number. If there are no doors in a room, it returns an empty table.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to check for doors in.<br />
<br />
: See also: [[#setDoor|setDoor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example that displays possible doors in room 2334<br />
local doors = getDoors(2334)<br />
<br />
if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end<br />
<br />
local door_status = {"open", "closed", "locked"}<br />
<br />
for direction, door in pairs(doors) do<br />
cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")<br />
end<br />
</syntaxhighlight><br />
<br />
==getExitStubs==<br />
;stubs = getExitStubs(roomid)<br />
<br />
:Returns an indexed table (starting at 0) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#connectExitStub|connectExitStub()]], [[#getExitStubs1|getExitStubs1()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
local stubs = getExitStubs(6)<br />
for i = 0, #stubs do print(stubs[i]) end<br />
</syntaxhighlight><br />
<br />
{{note}} Previously would throw a lua error on non-existent room - now returns nil plus error message (as does other run-time errors) - previously would return just a nil on NO exit stubs but now returns a notification error message as well, to aide disambiguation of the nil value.<br />
<br />
==getExitStubs1==<br />
;stubs = getExitStubs1(roomid)<br />
<br />
:Returns an indexed table (starting at 1) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. As this function starts indexing from 1 as it is default in Lua, you can use ipairs() to iterate over the results.<br />
<br />
; See also: [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end<br />
</syntaxhighlight><br />
<br />
==getExitWeights==<br />
;weights = getExitWeights(roomid)<br />
<br />
:Returns a key-value table of the exit weights that a room has, with the direction or special exit as a key and the value as the exit weight. If a weight for a direction wasn't yet set, it won't be listed.<br />
<br />
;Parameters<br />
* ''roomid:''<br />
: Room ID to view the exit weights in.<br />
<br />
: See also: [[#setExitWeight|setExitWeight()]]<br />
<br />
==getGridMode==<br />
;TrueOrFalse = getGridMode(areaID)<br />
<br />
:Use this to see, if a specific area has grid/wilderness view mode set. This way, you can also calculate from a script, how many grid areas a map has got in total.<br />
<br />
{{MudletVersion|3.11}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID (number) to view the grid mode of.<br />
<br />
: See also: [[#setGridMode|setGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getGridMode(55)<br />
-- will return: false<br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
getGridMode(55)<br />
-- will return: true<br />
</syntaxhighlight><br />
<br />
==getMapEvents==<br />
; mapevents = getMapEvents()<br />
<br />
: Returns a list of map events currently registered. Each event is a dictionary with the keys ''uniquename'', ''parent'', ''event name'', ''display name'', and ''arguments'', which correspond to the arguments of ''addMapEvent()''.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")<br />
<br />
local mapEvents = getMapEvents()<br />
for _, event in ipairs(mapEvents) do<br />
echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.3}}<br />
<br />
==getMapLabel==<br />
;labelinfo = getMapLabel(areaID, labelID or labelText)<br />
<br />
:Returns a key-value table describing that particular label in an area. Keys it contains are the ''X'', ''Y'', ''Z'' coordinates, ''Height'' and ''Width'', ''BgColor'', ''FgColor'', ''Pixmap'', and the ''Text'' it contains. If the label is an image label, then ''Text'' will be set to the ''no text'' string.<br />
<br />
:''BgColor'' and ''FgColor'' are tables with ''r'',''g'',''b'' keys, each holding ''0-255'' color component value.<br />
<br />
:''Pixmap'' is base64 encoded image of label.<br />
<br />
{{note}} ''BgColor'', ''FgColor'', ''Pixmap'' are available in Mudlet 4.11+<br />
<br />
;Parameters <br />
* ''areaID:'' areaID from which to retrieve label<br />
* ''labelID:'' labelID (''getMapLabels'' return table key) or labelText (exact match)<br />
<br />
See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabels|getMapLabels()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua getMapLabels(52)<br />
{<br />
"no text",<br />
[0] = "test"<br />
}<br />
<br />
lua getMapLabel(52, 0)<br />
{<br />
Y = -2,<br />
X = -8,<br />
Z = 11,<br />
Height = 3.9669418334961,<br />
Text = "test",<br />
Width = 8.6776866912842,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
<br />
lua getMapLabel(52, "no text")<br />
{<br />
Y = 8,<br />
X = -15,<br />
Z = 11,<br />
Height = 7.2520666122437,<br />
Text = "no text"<br />
Width = 11.21900844574,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapLabels==<br />
;arealabels = getMapLabels(areaID)<br />
<br />
:Returns an indexed table (that starts indexing from 0) of all of the labels in the area, plus their label text. You can use the label id to [[#deleteMapLabel|deleteMapLabel()]] it.<br />
:If there are no labels in the area at all, it will return an empty table.<br />
<br />
: See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabel|getMapLabel()]], [[#deleteMapLabel|deleteMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapLabels(43))<br />
table {<br />
0: ''<br />
1: 'Waterways'<br />
}<br />
<br />
deleteMapLabel(43, 0)<br />
display(getMapLabels(43))<br />
table {<br />
1: 'Waterways'<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapMenus==<br />
;getMapMenus()<br />
<br />
:Returns a table with the available map menus as key-value in the format of <code>map menu - parent item</code>. If an item is positioned at the menu's top-level, the value will say <code>top-level</code>.<br />
:If you haven't opened a map yet, getMapMenus() will return nil+error message. If you don't have any map labels yet, an empty table <code>{}</code> is returned.<br />
<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- given the following menu structure:<br />
top-level<br />
menu1<br />
menu1.1<br />
action1.1.1<br />
menu1.2<br />
action1.2.1<br />
menu2<br />
<br />
getMapMenus() -- will return:<br />
{<br />
menu2 = "top-level",<br />
menu1.2 = "menu1",<br />
menu1.1 = "menu1",<br />
menu1 = "top-level"<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapSelection==<br />
; getMapSelection()<br />
<br />
:Returns a table containing details of the current mouse selection in the 2D mapper.<br />
<br />
:Reports on one or more rooms being selected (i.e. they are highlighted in orange).<br />
<br />
:The contents of the table will vary depending on what is currently selected. If the selection is of map rooms then there will be keys of ''center'' and ''rooms'': the former will indicates the center room (the one with the yellow cross-hairs) if there is more than one room selected or the only room if there is only one selected (there will not be cross-hairs in that case); the latter will contain a list of the one or more rooms.<br />
<br />
; Example - several rooms selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5011,<br />
5012,<br />
5013,<br />
5014,<br />
5018,<br />
5019,<br />
5020<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - one room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5013<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - no or something other than a room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==getMapUserData==<br />
;getMapUserData( key )<br />
<br />
;Parameters<br />
* ''key:''<br />
: string used as a key to select the data stored in the map as a whole.<br />
<br />
:Returns the user data item (string); will return a nil+error message if there is no data with such a key in the map data.<br />
<br />
: See also: [[#getAllMapUserData|getAllMapUserData()]], [[#setMapUserData|setMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapUserData("last updated"))<br />
--might result in:--<br />
"December 5, 2020"<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getMapZoom==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''4.17.0''''' also with the option to get the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet remembering the zoom level last used for each area and with the revision of the ''setMapZoom()'' function to also take an areaID to work on instead of the current area being viewed in the map.<br />
<br />
:See also: [[Manual:Mapper_Functions#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| 4.17.0}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is ''3.0'' and the initial value - and what prior Mudlet versions started each session with - is ''20.0''.<br />
<br />
==getPath==<br />
;getPath(roomID from, roomID to)<br />
<br />
:Returns a boolean true/false if a path between two room IDs is possible. If it is, the global ''speedWalkDir'' table is set to all of the directions that have to be taken to get there, and the global ''speedWalkPath'' table is set to all of the roomIDs you'll encounter on the way, and as of 3.0, ''speedWalkWeight'' will return all of the room weights. Additionally returns the total cost (all weights added up) of the path after the boolean argument in 3.0.<br />
<br />
<br />
: See also: [[Manual:Lua_Functions#translateTable|translateTable()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if we can go to room 155 from room 34 - if yes, go to it<br />
if getPath(34,155) then<br />
gotoRoom(155)<br />
else<br />
echo("\nCan't go there!")<br />
end<br />
</syntaxhighlight><br />
<br />
==getPlayerRoom==<br />
;getPlayerRoom()<br />
<br />
:Returns the current player location as set by [[#centerview|centerview()]].<br />
<br />
: See also: [[#centerview|centerview]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("We're currently in " .. getRoomName(getPlayerRoom()))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.14}}<br />
<br />
==getRoomArea==<br />
;getRoomArea(roomID)<br />
<br />
:Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by [[#getAreaTable | getAreaTable()]] function, or use the [[#getRoomAreaName |getRoomAreaName()]] function.<br />
<br />
{{note}} If the room ID does not exist, this function will raise an error.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Area ID of room #100 is: "..getRoomArea(100))<br />
<br />
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))<br />
</syntaxhighlight><br />
<br />
==getRoomAreaName==<br />
;getRoomAreaName(areaID or areaName)<br />
<br />
:Returns the area name for a given area id; or the area id for a given area name.<br />
<br />
{{note}} Despite the name, this function will not return the area name for a given ''room'' id (or room name) directly. However, renaming or revising it would break existing scripts.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))<br />
</syntaxhighlight><br />
<br />
<br />
==getRoomChar==<br />
;getRoomChar(roomID)<br />
<br />
:Returns the single ASCII character that forms the ''symbol'' for the given room id.<br />
<br />
: '''Since Mudlet version 3.8 :''' this facility has been extended:<br />
: Returns the string (UTF-8) that forms the ''symbol'' for the given room id; this may have been set with either [[#setRoomChar|setRoomChar()]] or with the ''symbol'' (was ''letter'' in prior versions) context menu item for rooms in the 2D Map.<br />
<br />
==getRoomCharColor==<br />
;r,g,b = getRoomCharColor(roomID)<br />
<br />
:Returns the color of the Room Character as a set of r,g,b color coordinates.<br />
<br />
;See also: [[Manual:Lua_Functions#setRoomCharColor|setRoomCharColor()]], [[Manual:Lua_Functions#getRoomChar|getRoomChar()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room ID to get the room character color from<br />
<br />
;Returns <br />
* The color as 3 separate numbers, red, green, and blue from 0-255<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0<br />
local r,g,b = getRoomCharColor(12345)<br />
decho(f"Room Character for room 12345 is <{r},{g},{b}>this color.<r> It is made up of <{r},0,0>{r} red<r>, <0,{g},0>{g} green<r>, <0,0,{b}> {b} blue<r>.\")<br />
</syntaxhighlight><br />
<br />
==getRoomCoordinates==<br />
;x,y,z = getRoomCoordinates(roomID)<br />
<br />
:Returns the room coordinates of the given room ID.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local x,y,z = getRoomCoordinates(roomID)<br />
echo("Room Coordinates for "..roomID..":")<br />
echo("\n X:"..x)<br />
echo("\n Y:"..y)<br />
echo("\n Z:"..z)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- A quick function that will find all rooms on the same z-position in an area; this is useful if, say, you want to know what all the same rooms on the same "level" of an area is.<br />
function sortByZ(areaID, zval)<br />
local area = getAreaRooms(areaID)<br />
local t = {}<br />
for _, id in ipairs(area) do<br />
local _, _, z = getRoomCoordinates(id)<br />
if z == zval then<br />
table.insert(t, id)<br />
end<br />
end<br />
return t<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomEnv==<br />
;envID = getRoomEnv(roomID)<br />
<br />
:Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function checkID(id)<br />
echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))<br />
end<br />
</syntaxhighlight><br />
<br />
== getRoomExits ==<br />
;getRoomExits (roomID)<br />
:Returns the currently known non-special exits for a room in an key-index form: ''exit = exitroomid''.<br />
<br />
: See also: [[#getSpecialExits|getSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
table {<br />
'northwest': 80<br />
'east': 78<br />
}<br />
</syntaxhighlight><br />
<br />
Here's a practical example that queries the rooms around you and searched for one of the water environments (the number would depend on how it was mapped):<br />
<br />
<syntaxhighlight lang="lua"><br />
local exits = getRoomExits(mycurrentroomid)<br />
for direction,num in pairs(exits) do<br />
local env_num = getRoomEnv(num)<br />
if env_num == 22 or env_num == 20 or env_num == 30 then<br />
print("There's water to the "..direction.."!")<br />
end<br />
end</syntaxhighlight><br />
<br />
==getRoomHashByID==<br />
;getRoomHashByID(roomID)<br />
<br />
:Returns a room hash that is associated with a given room ID in the mapper. This is primarily for games that make use of hashes instead of room IDs. It may be used to share map data while not sharing map itself. ''nil'' is returned if no room is not found.<br />
<br />
: See also: [[#getRoomIDbyHash|getRoomIDbyHash()]]<br />
{{MudletVersion|3.13.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
for id,name in pairs(getRooms()) do<br />
local h = getRoomUserData(id, "herbs")<br />
if h ~= "" then<br />
echo(string.format([[["%s"] = "%s",]], getRoomHashByID(id), h))<br />
echo("\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomIDbyHash==<br />
;roomID = getRoomIDbyHash(hash)<br />
<br />
:Returns a room ID that is associated with a given hash in the mapper. This is primarily for games that make use of hashes instead of room IDs (like [http://avalon.mud.de/index.php?enter=1 Avalon.de]). ''-1'' is returned if no room ID matches the hash.<br />
<br />
: See also: [[#getRoomHashByID|getRoomHashByID()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177<br />
local id = getRoomIDbyHash("5dfe55b0c8d769e865fd85ba63127fbc")<br />
if id == -1 then <br />
id = createRoomID()<br />
setRoomIDbyHash(id, "5dfe55b0c8d769e865fd85ba63127fbc")<br />
addRoom(id)<br />
setRoomCoordinates(id, 0, 0, -1)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomName==<br />
;getRoomName(roomID)<br />
<br />
:Returns the room name for a given room id.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("The name of the room id #455 is %s.", getRoomName(455))<br />
</syntaxhighlight><br />
<br />
==getRooms==<br />
;rooms = getRooms()<br />
<br />
:Returns the list of '''all''' rooms in the map in the whole map in roomid - room name format.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- simple, raw viewer for rooms in the world<br />
display(getRooms())<br />
<br />
-- iterate over all rooms in code<br />
for id,name in pairs(getRooms()) do<br />
print(id, name)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomsByPosition==<br />
;roomTable = getRoomsByPosition(areaID, x,y,z)<br />
<br />
:Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.<br />
<br />
{{note}} The returned table starts indexing from '''0''' and not the usual lua index of '''1''', which means that using '''#''' to count the size of the returned table will produce erroneous results - use [[Manual:Table_Functions#table.size|table.size()]] instead.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sample alias to determine a room nearby, given a relative direction from the current room<br />
<br />
local otherroom<br />
if matches[2] == "" then<br />
local w = matches[3]<br />
local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)<br />
local has = table.contains<br />
if has({"west", "left", "w", "l"}, w) then<br />
x = (x or ox) - 1; y = (y or oy); z = (z or oz)<br />
elseif has({"east", "right", "e", "r"}, w) then<br />
x = (x or ox) + 1; y = (y or oy); z = (z or oz)<br />
elseif has({"north", "top", "n", "t"}, w) then<br />
x = (x or ox); y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"south", "bottom", "s", "b"}, w) then<br />
x = (x or ox); y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"northwest", "topleft", "nw", "tl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"northeast", "topright", "ne", "tr"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"southeast", "bottomright", "se", "br"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"up", "u"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) + 1<br />
elseif has({"down", "d"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) - 1<br />
end<br />
<br />
local carea = getRoomArea(mmp.currentroom)<br />
if not carea then mmp.echo("Don't know what area are we in.") return end<br />
<br />
otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))<br />
<br />
if not otherroom then<br />
mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return<br />
else<br />
mmp.echo("The room "..w.." of us has an ID of "..otherroom)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomUserData==<br />
;getRoomUserData(roomID, key)<br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or "" if none is stored. Use [[#setRoomUserData|setRoomUserData()]] function for setting the user data.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserData(341, "visitcount"))<br />
</syntaxhighlight><br />
<br />
:;getRoomUserData(roomID, key, enableFullErrorReporting)<br />
<br />
::Returns the user data value (string) stored at a given room with a given key (string), or, if the boolean value ''enableFullErrorReporting'' is true, ''nil'' and an error message if the key is not present or the room does not exist; if ''enableFullErrorReporting'' is false an empty string is returned but then it is not possible to tell if that particular value is actually stored or not against the given key.<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<!-- I would like this block to be indented to match the Example header but the mark-up system seems to be broken and only includes the first line<br />
if the start of the code line begins: ":<lua>..."--><br />
<syntaxhighlight lang="lua">local vNum = 341<br />
result, errMsg = getRoomUserData(vNum, "visitcount", true)<br />
if result ~= nil then<br />
display(result)<br />
else<br />
echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")<br />
end</syntaxhighlight><br />
<br />
==getRoomUserDataKeys==<br />
;getRoomUserDataKeys(roomID)<br />
<br />
:Returns all the keys for user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserDataKeys(3441))<br />
--might result in:--<br />
{<br />
"description",<br />
"doorname_up",<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getRoomWeight==<br />
;getRoomWeight(roomID)<br />
<br />
:Returns the weight of a room. By default, all new rooms have a weight of 1.<br />
: See also: [[#setRoomWeight|setRoomWeight()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Original weight of room 541: "..getRoomWeight(541))<br />
setRoomWeight(541, 3)<br />
display("New weight of room 541: "..getRoomWeight(541))<br />
</syntaxhighlight><br />
<br />
==getSpecialExits==<br />
;exits = getSpecialExits(roomID[, listAllExits])<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the special exits of.<br />
* ''listAllExits:''<br />
: (Since ''TBA'') In the case where there is more than one special exit to the same room ID list all of them.<br />
<br />
:Returns a roomid table of sub-tables containing name/command and exit lock status, of the special exits in the room. If there are no special exits in the room, the table returned will be empty.<br />
:Before ''TBA'' (likely to be Mudlet version '''4.11.0'''), if more than one special exit goes to the ''same'' exit room id then one of those exits is returned at random. Since ''TBA'' this will be the best (i.e. lowest-weight) exit that is '''not''' locked; should none be unlocked then the lowest locked one will be listed. In case of a tie, one of the tying exits will be picked at random.<br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- There are three special exits from 1337 to the room 42:<br />
-- "climb down ladder" which is locked and has an exit weight of 10<br />
-- "step out window" which is unlocked and has an exit weight of 20<br />
-- "jump out window" which is unlocked and has an exit weight of 990<br />
getSpecialExits(1337)<br />
<br />
-- In 4.10.1 and before this could results in:<br />
table {<br />
42 = {"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"climb down ladder" = "1"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA this will return:<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA, with the second argument as true, this gives:<br />
getSpecialExits(1337, true)<br />
table {<br />
42 = {"step out window" = "0",<br />
"climb down ladder" = "1",<br />
"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
</syntaxhighlight><br />
<br />
==getSpecialExitsSwap==<br />
;getSpecialExitsSwap(roomID)<br />
<br />
:Very similar to [[#getSpecialExits|getSpecialExits()]] function, but returns the rooms in the command - roomid style.<br />
<br />
==gotoRoom==<br />
;gotoRoom (roomID)<br />
:Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".<br />
<br />
In case this isn't working, and you are coding your own mapping script, [[Manual:Mapper#Making_your_own_mapping_script|see here]] how to implement additional functionality necessary.<br />
<br />
==hasExitLock==<br />
;status = hasExitLock(roomID, direction)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
-- check if the east exit of room 1201 is locked<br />
display(hasExitLock(1201, 4))<br />
display(hasExitLock(1201, "e"))<br />
display(hasExitLock(1201, "east"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#lockExit|lockExit()]]<br />
<br />
==hasSpecialExitLock==<br />
;hasSpecialExitLock(from roomID, to roomID, moveCommand)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. ''moveCommand'' is the action to take to get through the gate.<br />
<br />
See also: [[#lockSpecialExit|lockSpecialExit()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command<br />
lockSpecialExit(17463, 7814, 'enter feather', true)<br />
<br />
-- see if it is locked: it will say 'true', it is<br />
display(hasSpecialExitLock(17463, 7814, 'enter feather'))<br />
</syntaxhighlight><br />
<br />
==highlightRoom==<br />
;highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)<br />
<br />
:Highlights a room with the given color, which will override its environment color. If you use two different colors, then there'll be a shading from the center going outwards that changes into the other color. <br />
<br />
;Parameters<br />
* ''roomID''<br />
: ID of the room to be colored.<br />
* ''color1Red, color1Green, color1Blue''<br />
: RGB values of the first color.<br />
* ''color2Red, color2Green, color2Blue''<br />
: RGB values of the second color.<br />
* ''highlightRadius'' <br />
: The radius for the highlight circle - if you don't want rooms beside each other to overlap, use ''1'' as the radius. <br />
* ''color1Alpha'' and ''color2Alpha'' <br />
: Transparency values from 0 (completely transparent) to 255 (not transparent at all).<br />
<br />
: See also: [[#unHighlightRoom|unHighlightRoom()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- color room #351 red to blue<br />
local r,g,b = unpack(color_table.red)<br />
local br,bg,bb = unpack(color_table.blue)<br />
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)<br />
</syntaxhighlight><br />
<br />
==killMapInfo==<br />
;killMapInfo(label)<br />
<br />
Delete a map info contributor entirely - it will be not available anymore.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be removed was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==loadJsonMap==<br />
; loadJsonMap(pathFileName)<br />
<br />
; Parameters:<br />
<br />
* ''pathFileName'' a string that is an absolute path and file name to read the data from.<br />
<br />
Load the Mudlet map in text (JSON) format. It does take longer than loading usual map file (''.dat'' in binary) so it will show a progress dialog.<br />
<br />
: See also: [[#saveJsonMap|saveJsonMap()]]<br />
<br />
Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11.0}}<br />
<br />
==loadMap==<br />
;loadMap(file location)<br />
<br />
:Loads the map file from a given location. The map file must be in Mudlet's format - saved with [[#saveMap|saveMap()]] or, as of the Mudlet 3.0 may be a MMP XML map conforming to the structure used by I.R.E. for their downloadable maps for their MUD games. <br />
<br />
:Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.<br />
<br />
:Using no arguments will load the last saved map.<br />
<br />
<syntaxhighlight lang="lua"><br />
loadMap("/home/user/Desktop/Mudlet Map.dat")<br />
</syntaxhighlight><br />
<br />
{{Note}} A file name ending with <code>.xml</code> will indicate the XML format.<br />
<br />
==lockExit==<br />
;lockExit(roomID, direction, lockIfTrue)<br />
<br />
:Locks a given exit from a room. The destination may remain accessible through other paths, unlike [[#lockRoom|lockRoom]]. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
: See also: [[#hasExitLock|hasExitLock()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- lock the east exit of room 1201 so we never path through it<br />
lockExit(1201, 4, true)<br />
</syntaxhighlight><br />
<br />
==lockRoom==<br />
;lockRoom (roomID, lockIfTrue)<br />
<br />
:Locks a given room id from future speed walks (thus the mapper will never path through that room).<br />
: See also: [[#roomLocked | roomLocked()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockRoom(1, true) -- locks a room if from being walked through when speedwalking.<br />
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.<br />
</syntaxhighlight><br />
<br />
==lockSpecialExit==<br />
;lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)<br />
<br />
:Locks a given special exit, leading from one specific room to another that uses a certain command from future speed walks (thus the mapper will never path through that special exit).<br />
: See also: [[#hasSpecialExitLock | hasSpecialExitLock()]], [[#lockExit | lockExit()]], [[#lockRoom | lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2<br />
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit<br />
</syntaxhighlight><br />
<br />
==moveMapWidget==<br />
;moveMapWidget(Xpos, Ypos)<br />
:moves the map window to the given position.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
;Parameters<br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==openMapWidget==<br />
;openMapWidget([dockingArea | Xpos, Ypos, width, height])<br />
means either of these are fine:<br />
;openMapWidget()<br />
;openMapWidget(dockingArea)<br />
;openMapWidget(Xpos, Ypos, width, height)<br />
<br />
:opens a map window with given options.<br />
<br />
: See also: [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
{{note}} If no parameter is given the map window will be opened with the saved layout or at the right docking position (similar to clicking the icon)<br />
* ''dockingArea:''<br />
: If only one parameter is given this parameter will be a string that contains one of the possible docking areas the map window will be created in (f" floating "t" top "b" bottom "r" right and "l" left)<br />
{{note}} If 4 parameters are given the map window will be created in floating state <br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''width:''<br />
: The width map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height map window, in pixels. Passed as an integer number.<br />
<br />
==pauseSpeedwalk==<br />
;pauseSpeedwalk()<br />
<br />
:Pauses a speedwalk started using [[#speedwalk|speedwalk()]]<br />
<br />
: See also: [[#speedwalk|speedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = pauseSpeedwalk()<br />
if not ok then<br />
debugc(f"Error: unable to pause speedwalk because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
==registerMapInfo==<br />
;registerMapInfo(label, function)<br />
<br />
Adds an extra 'map info' to the mapper widget which can be used to display custom information.<br />
<br />
: See also: [[#killMapInfo|killMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
{{note}}<br />
You can register multiple map infos - just give them unique names and toggle whichever ones you need.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info will be registered and visible in select box under mapper. You can use it later to kill map info, enable it, disable it or overwrite using [[#registerMapInfo|registerMapInfo()]] again.<br />
* ''function:''<br />
: Callback function that will be responsible for returning information how to draw map info fragment.<br />
<br />
Callback function is called with following arguments:<br />
* ''roomId'' - current roomId or currently selected room (when multiple selection is made this is center room)<br />
* ''selectionSize'' - how many rooms are selected<br />
* ''areaId'' - roomId's areaId<br />
* ''displayedAreaId'' - areaId that is currently displayed<br />
<br />
Callback needs to return following:<br />
* ''text'' - text that will be displayed (when empty, nothing will be displayed, if you want to "reserve" line or lines use not empty value " " or add line breaks "\n")<br />
* ''isBold'' (optional) - true/false - determines whether text will be bold <br />
* ''isItalic'' (optional) - true/false - determines whether text will be italic<br />
* ''color r'' (optional) - color of text red component (0-255)<br />
* ''color g'' (optional) - color of text green component (0-255)<br />
* ''color b'' (optional) - color of text blue component (0-255)<br />
<br />
{{note}}<br />
Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.<br />
<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea) <br />
return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),<br />
true, true, 0, 255, 0<br />
end)<br />
enableMapInfo("My very own handler!")<br />
</syntaxhighlight><br />
<br />
Example will display something like that:<br />
<br />
[[File:Map-info-example.png]]<br />
<br />
Using function arguments is completely optional and you can determine whether and how to display map info completely externally.<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("Alert", function() <br />
if character.hp < 20 then<br />
return "Look out! Your HP is getting low", true, false, unpack(color_table.red) -- will display red, bolded warning whne character.hp is below 20<br />
else<br />
return "" -- will not return anything<br />
end<br />
end)<br />
enableMapInfo("Alert")<br />
</syntaxhighlight><br />
<br />
==resumeSpeedwalk==<br />
;resumeSpeedwalk()<br />
<br />
:Continues a speedwalk paused using [[#pauseSpeedwalk|pauseSpeedwalk()]]<br />
: See also: [[#speedwalk|speedwalk()]], [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = resumeSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")<br />
return<br />
end<br />
cecho("\n<green>Successfully resumed speedwalk!\n")<br />
</syntaxhighlight><br />
<br />
==removeCustomLine==<br />
;removeCustomLine(roomID, direction) <br />
<br />
:Removes the custom exit line that's associated with a specific exit of a room.<br />
:See also: [[#addCustomLine|addCustomLine()]], [[#getCustomLines|getCustomLines()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- remove custom exit line that starts in room 315 going north<br />
removeCustomLine(315, "n")<br />
</syntaxhighlight><br />
<br />
==removeMapEvent==<br />
;removeMapEvent(event name)<br />
<br />
:Removes the given menu entry from a mappers right-click menu. You can add custom ones with [[#addMapEvent | addMapEvent()]].<br />
: See also: [[#addMapEvent | addMapEvent()]], [[#getMapEvents | getMapEvents()]], [[#removeMapMenu | removeMapMenu()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- add one to the general menu<br />
removeMapEvent("room a") -- removes the said menu<br />
</syntaxhighlight><br />
<br />
==removeMapMenu==<br />
;removeMapMenu(menu name)<br />
<br />
:Removes the given submenu from a mappers right-click menu. You can add custom ones with [[#addMapMenu | addMapMenu()]].<br />
: See also: [[#addMapMenu | addMapMenu()]], [[#getMapMenus | getMapMenus()]], [[#removeMapEvent | removeMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Test") -- add submenu to the general menu<br />
removeMapMenu("Test") -- removes that same menu again<br />
</syntaxhighlight><br />
<br />
==removeSpecialExit==<br />
;removeSpecialExit(roomID, command) <br />
<br />
:Removes the special exit which is accessed by ''command'' from the room with the given ''roomID''.<br />
:See also: [[#addSpecialExit|addSpecialExit()]], [[#clearSpecialExits|clearSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2<br />
removeSpecialExit(1, "pull rope") -- removes the exit again<br />
</syntaxhighlight><br />
<br />
==resetRoomArea==<br />
;resetRoomArea (roomID)<br />
<br />
: Unassigns the room from its given area. While not assigned, its area ID will be -1. Note that since Mudlet 3.0 the "default area" which has the id of -1 may be selectable in the area selection widget on the mapper - although there is also an option to conceal this in the settings.<br />
<br />
: See also: [[#setRoomArea | setRoomArea()]], [[#getRoomArea | getRoomArea()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetRoomArea(3143)<br />
</syntaxhighlight><br />
<br />
==resizeMapWidget==<br />
;resizeMapWidget(width, height)<br />
:resizes a map window with given width, height.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
* ''width:''<br />
: The width of the map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the map window, in pixels. Passed as an integer number.<br />
<br />
==roomExists==<br />
;roomExists(roomID)<br />
<br />
:Returns a boolean true/false depending if the room with that ID exists (is created) or not.<br />
<br />
==roomLocked==<br />
;locked = roomLocked(roomID)<br />
<br />
:Returns true or false whenever a given room is locked.<br />
: See also: [[#lockRoom|lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))<br />
</syntaxhighlight><br />
<br />
==saveJsonMap==<br />
; saveJsonMap([pathFileName])<br />
Saves all the data that is normally held in the Mudlet map (''.dat'' as a binary format) in text (JSON) format. It does take longer to do this, so a progress dialog will be shown indicating the status. <br />
<br />
: See also: [[#loadJsonMap|loadJsonMap()]]<br />
{{MudletVersion|4.11.0}}<br />
<br />
; Parameters:<br />
* ''pathFileName'' (optional in Mudlet 4.12+): a string that is an absolute path and file name to save the data into.<br />
<br />
; Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
==saveMap==<br />
;saveMap([location], [version])<br />
<br />
:Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work. You can also save the map in the Mapper settings tab.<br />
<br />
;Parameters<br />
* ''location''<br />
: (optional) save the map to the given location if provided, or the default one otherwise.<br />
* ''version''<br />
: (optional) map version as a number to use when saving (Mudlet 3.17+)<br />
<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")<br />
if not savedok then<br />
echo("Couldn't save :(\n")<br />
else<br />
echo("Saved fine!\n")<br />
end<br />
<br />
-- save with a particular map version<br />
saveMap(20)<br />
</syntaxhighlight><br />
<br />
==searchAreaUserData==<br />
;searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])<br />
:Searches Areas' User Data in a manner exactly the same as [[#searchRoomUserData|searchRoomUserData()]] does in all Rooms' User Data, refer to that command for the specific details except to replace references to rooms and room ID numbers there with areas and areas ID numbers.<br />
<br />
==searchRoom== <br />
;searchRoom (room number | room name[, case-sensitive [, exact-match]])<br />
:Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of ''roomid = roomname'', the optional second and third boolean parameters have been available since Mudlet 3.0;<br />
<br />
::If no rooms are found, then an empty table is returned.<br />
<br />
:If you pass it a '''number''' instead of a '''string''' as just one argument, it'll act like [[#getRoomName|getRoomName()]] and return the room name.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- show the behavior when given a room number:<br />
display(searchRoom(3088))<br />
"The North Road South of Taren Ferry"<br />
<br />
-- show the behavior when given a string:<br />
-- shows all rooms containing the text in any case:<br />
display(searchRoom("North road"))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road",<br />
[3146] = "Bend in the North Road",<br />
[3088] = "The North Road South of Taren Ferry",<br />
[6229] = "Grassy Field By North Road"<br />
}<br />
-- or:<br />
-- display(searchRoom("North road",false))<br />
-- display(searchRoom("North road",false,false))<br />
-- would both also produce those results.<br />
<br />
-- shows all rooms containing the text in ONLY the letter-case provided:<br />
display(searchRoom("North road",true,false))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3117] = "North road",<br />
}<br />
<br />
-- shows all rooms containing ONLY that text in either letter-case:<br />
lua searchRoom("North road",false,true)<br />
{<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road"<br />
}<br />
<br />
-- shows all rooms containing only and exactly the given text:<br />
lua searchRoom("North road",true,true)<br />
{<br />
[3115] = "North road",<br />
[3117] = "North road"<br />
}<br />
</syntaxhighlight><br />
{{note}} Technically, with both options (case-sensitive and exact-match) set to true, one could just return a list of numbers as we know precisely what the string will be, but it was kept the same for maximum flexibility in user scripts.<br />
<br />
==searchRoomUserData== <br />
;searchRoomUserData([key, [value]])<br />
:A command with three variants that search though all the rooms in sequence (so '''not as fast as a user built/maintained ''index'' system''') and find/reports on the room user data stored:<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;searchRoomUserData(key, value)<br />
<br />
:Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key". <br />
<br />
;searchRoomUserData(key)<br />
<br />
:Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key". <br />
<br />
;searchRoomUserData()<br />
<br />
:Reports a (sorted) list of the unique keys from all rooms with user data with any (case sensitive) "key", available since Mudlet 3.0. It is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if I had stored the details of "named doors" as part of the room user data --<br />
display(searchRoomUserData("doorname_up"))<br />
<br />
--[[ could result in a list:<br />
{<br />
"Eastgate",<br />
"Northgate",<br />
"boulderdoor",<br />
"chamberdoor",<br />
"dirt",<br />
"floorboards",<br />
"floortrap",<br />
"grate",<br />
"irongrate",<br />
"rockwall",<br />
"tomb",<br />
"trap",<br />
"trapdoor"<br />
}]]<br />
<br />
-- then taking one of these keys --<br />
display(searchRoomUserData("doorname_up","trapdoor"))<br />
<br />
--[[ might result in a list:<br />
{<br />
3441,<br />
6113,<br />
6115,<br />
8890<br />
}<br />
]]</syntaxhighlight><br />
<br />
==setAreaName==<br />
;setAreaName(areaID or areaName, newName)<br />
<br />
:Names, or renames an existing area to the new name. The area must be created first with [[#addAreaName|addAreaName()]] and it must be unique.<br />
<br />
{{note}} parameter areaName is available since Mudlet 3.0.<br />
<br />
:See also: [[#deleteArea|deleteArea()]], [[#addAreaName|addAreaName()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setAreaName(2, "My city")<br />
<br />
-- available since Mudlet 3.0<br />
setAreaName("My old city name", "My new city name")<br />
</syntaxhighlight><br />
<br />
==setAreaUserData==<br />
;setAreaUserData(areaID, key (as a string), value (as a string))<br />
<br />
:Stores information about an area under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. Returns a lua ''true'' value on success. You can have as many keys as you'd like, however a blank key will not be accepted and will produce a lua ''nil'' and an error message instead.<br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#getAreaUserData|getAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store extra area details...<br />
setAreaUserData(34, "country", "Andor.")<br />
<br />
-- or a sound file to play in the background (with a script that checks a room's area when entered)...<br />
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))<br />
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)<br />
</syntaxhighlight><br />
<br />
==setCustomEnvColor==<br />
;setCustomEnvColor(environmentID, r,g,b,a)<br />
<br />
:Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.<br />
: See also: [[#getCustomEnvColorTable|getCustomEnvColorTable()]], [[#setRoomEnv|setRoomEnv()]]<br />
<br />
{{note}} Numbers 1-16 and 257-272 are reserved by Mudlet. 257-272 are the default colors the user can adjust in mapper settings, so feel free to use them if you'd like - but don't overwrite them with this function.<br />
<br />
[[File:Screenshot 20240305 115555.png|thumb|center|Default colour table for Mudlet mapper.]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200<br />
local r,g,b = unpack(color_table.blue)<br />
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue<br />
</syntaxhighlight><br />
<br />
==setDoor==<br />
;setDoor(roomID, exitCommand, doorStatus)<br />
<br />
:Creates or deletes a door in a room. Doors are purely visual - they don't affect pathfinding. You can use the information to adjust your speedwalking path based on the door information in a room, though.<br />
<br />
:Doors CAN be set on stub exits ''- so that map makers can note if there is an obvious door to somewhere even if they do not (yet) know where it goes, perhaps because they do not yet have the key to open it!''<br />
<br />
:Returns ''true'' if the change could be made, ''false'' if the input was valid but ineffective (door status was not changed), and ''nil'' with a message string on invalid input (value type errors).<br />
<br />
: See also: [[#getDoors|getDoors()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to create the door in.<br />
* ''exitCommand:''<br />
: The cardinal direction for the door is in - it can be one of the following: '''n''', '''e''', '''s''', '''w''', '''ne''', '''se''', '''sw''', '''ne'''. ''{Plans are afoot to add support for doors on the other normal exits: '''up''', '''down''', '''in''' and '''out''', and also on special exits - though more work will be needed for them to be shown in the mapper.}'' It is important to ONLY use these direction codes as others e.g. "UP" will be accepted - because a special exit could have ANY name/lua script - but it will not be associated with the particular normal exit - recent map auditing code about to go into the code base will REMOVE door and other room exit items for which the appropriate exit (or stub) itself is not present, so in this case, in the absence of a special exit called "UP" that example door will not persist and not show on the normal "up" exit when that is possible later on.<br />
<br />
* ''doorStatus:''<br />
: The door status as a number - '''0''' means no (or remove) door, '''1''' means open door (will draw a green square on exit), '''2''' means closed door (yellow square) and '''3''' means locked door (red square). <br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a door on the east exit of room 4234 that is currently open<br />
setDoor(4234, 'e', 1)<br />
<br />
-- remove a door from room 923 that points north<br />
setDoor(923, 'n', 0)<br />
</syntaxhighlight><br />
<br />
==setExit==<br />
;setExit(from roomID, to roomID, direction)<br />
<br />
:Creates a one-way exit from one room to another using a standard direction - which can be either one of ''n, ne, nw, e, w, s, se, sw, u, d, in, out'', the long version of a direction, or a number which represents a direction. If there was an exit stub in that direction already, then it will be automatically deleted for you.<br />
<br />
:Returns ''false'' if the exit creation didn't work.<br />
<br />
: See also: [[#addSpecialExit|addSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^exit (\d+) (\d+) (\w+)$<br />
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north<br />
<br />
if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then<br />
echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))<br />
else<br />
echo("Failed to set the exit.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
This function can also delete exits from a room if you use it like so:<br />
<br />
<syntaxhighlight lang="lua">setExit(from roomID, -1, direction)</syntaxhighlight><br />
<br />
- which will delete an outgoing exit in the specified direction from a room.<br />
<br />
==setExitStub==<br />
;setExitStub(roomID, direction, set/unset)<br />
<br />
Creates or removes an exit stub from a room in a given directions. You can use exit stubs later on to connect rooms that you're sure of are together. Exit stubs are also shown visually on the map, so the mapper can easily tell which rooms need finishing.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room to place an exit stub in, as a number.<br />
* ''direction:''<br />
: The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.<br />
* ''set/unset:''<br />
: A boolean to create or delete the exit stub.<br />
<br />
: See also: [[#getExitStubs|getExitStubs()]], [[#connectExitStub|connectExitStub()]]<br />
<br />
;Example<br />
Create an exit stub to the south from room 8:<br />
<syntaxhighlight lang="lua"><br />
setExitStub(8, "s", true)<br />
</syntaxhighlight><br />
<br />
How to delete all exit stubs in a room:<br />
<syntaxhighlight lang="lua"><br />
for i,v in pairs(getExitStubs(roomID)) do<br />
setExitStub(roomID, v,false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setExitWeight==<br />
;setExitWeight(roomID, exitCommand, weight)<br />
<br />
:Gives an exit a weight, which makes it less likely to be chosen for pathfinding. All exits have a weight of 0 by default, which you can increase. Exit weights are set one-way on an exit - if you'd like the weight to be applied both ways, set it from the reverse room and direction as well.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set the weight in.<br />
* ''exitCommand:''<br />
: The direction for the exit is in - it can be one of the following: '''n''', '''ne''', '''e''', '''se''', '''s''', '''sw''', '''w''', '''nw''', '''up''', '''down''', '''in''', '''out''', or, if it's a special exit, the special exit command - note that the strings for normal exits are case-sensitive and must currently be exactly as given here.<br />
* ''weight:''<br />
: Exit weight - by default, all exits have a weight of 0 meaning that the weight of the ''destination room'' is use when the route finding code is considering whether to use that exit; setting a value for an exit can increase or decrease the chance of that exit/destination room being used for a route by the route-finding code. For example, if the destination room has very high weight compared to it's neighbors but the exit has a low value then that exit and thus the room is more likely to be used than if the exit was not weighted.<br />
<br />
: See also: [[#getExitWeights|getExitWeights()]]<br />
<br />
==setGridMode==<br />
;setGridMode(areaID, true/false)<br />
<br />
:Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode; for the 2D map the custom exit lines will also not be shown if this mode is enabled. <br />
:Returns true if the area exists, otherwise false.<br />
:[[File:Mapper-regular-mode.png|none|thumb|640x640px|regular mode]][[File:Mapper-grid-mode.png|none|thumb|631x631px|grid mode]]<br />
<br />
: See also: [[#getGridMode|getGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
</syntaxhighlight><br />
<br />
==setMapUserData==<br />
;setMapUserData(key (as a string), value (as a string))<br />
<br />
:Stores information about the map under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearMapUserData|clearMapUserData()]], [[#clearMapUserDataItem|clearMapUserDataItem()]], [[#getAllMapUserData|getAllMapUserData()]], [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- store general meta information about the map...<br />
setMapUserData("game_name", "Achaea Mudlet map")<br />
<br />
-- or who the author was<br />
setMapUserData("author", "Bob")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))<br />
display("Available game info in the map: ")<br />
display(yajl.to_value(getMapUserData("some table")))<br />
</syntaxhighlight><br />
<br />
==setMapZoom==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''4.17.0''''' to allow the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet permanently remembering (it is saved within the map file) the zoom level last used for each area and with the addition of the ''getMapZoom()'' function.<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapZoom|getMapZoom()]].<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
:(Optional and only since '''Mudlet ''4.17.0''''') Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''4.17.0''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is 3.0 and the initial value - and what prior Mudlet versions started each session with - is 20.0.<br />
<br />
==setRoomArea==<br />
;setRoomArea(roomID, newAreaID or newAreaName)<br />
<br />
:Assigns the given room to a new or different area. If the area is displayed in the mapper this will have the room be visually moved into the area as well.<br />
<br />
: See also: [[#resetRoomArea|resetRoomArea()]]<br />
<br />
==setRoomChar==<br />
;setRoomChar(roomID, character)<br />
<br />
:Originally designed for an area in grid mode, takes a single ASCII character and draws it on the rectangular background of the room in the 2D map.<br />
<br />
;Game-related symbols for your map<br />
* [https://github.com/toddfast/game-icons-net-font toddfast's font] - 3000+ scalable vector RPG icons from [https://game-icons.net game-icons.net], as well as a script to download the latest icons and generate a new font.<br />
* Pixel Kitchen's [https://www.fontspace.com/donjonikons-font-f30607 Donjonikon Font] - 10x10 fantasy and RPG-related icons.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomChar(431, "#")<br />
<br />
setRoomChar(123, "$")<br />
<br />
-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings<br />
setRoomChar(666, "👿")<br />
</syntaxhighlight><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><br />
<div style="font-weight:bold;line-height:1.6;">Historical version information</div><br />
<div class="mw-collapsible-content"><br />
:Since Mudlet version 3.8 this feature has been extended:<br />
:* This function will now take a short string of any printable characters as a room ''symbol'', and they will be shrunk to fit them all in horizontally but if they become too small that ''symbol'' may not be shown if the zoom is such that the room symbol is too small to be legible.<br />
:* As "_" is now a valid character an existing symbol may be erased with either a space " " or an empty string "" although neither may be effective in some previous versions of Mudlet.<br />
:* Should the rooms be set to be drawn as circles this is now accommodated and the symbol will be resized to fit the reduce drawing area this will cause.<br />
:* The range of characters that are available are now dependent on the '''fonts''' present in the system and a setting on the "Mapper" tab in the preferences that control whether a specific font is to be used for all symbols (which is best if a font is included as part of a game server package, but has the issue that it may not be displayable if the user does not have that font or chooses a different one) or any font in the user's system may be used (which is the default, but may not display the ''glyph'' {the particular representation of a ''grapheme'' in a particular font} that the original map creator expected). Should it not be possible to display the wanted symbol in the map because one or more of the required glyphs are not available in either the specified or any font depending on the setting then the ''replacement character'' (Unicode ''code-point'' U+FFFD '�') will be shown instead. To allow such missing symbols to be handled the "Mapper" tab on the preferences dialogue has an option to display:<br />
::* an indicator to show whether the symbol can be made just from the selected font (green tick), from the fonts available in the system (yellow warning triangle) or not at all (red cross)<br />
::* all the symbols used on the map and how they will be displayed both only using the selected font and all fonts<br />
::* the sequence of code-points used to create the symbol which will be useful when used in conjunction with character selection utilities such as ''charmap.exe'' on Windows and ''gucharmap'' on unix-like system<br />
::* a count of the rooms using the particular symbol<br />
::* a list, limited in entries of the first rooms using that symbol<br />
:* The font that is chosen to be used as the primary (or only) one for the room symbols is stored in the Mudlet map data so that setting will be included if a binary map is shared to other Mudlet users or profiles on the same system.<br />
</div></div></div><br />
<br />
<br />
: See also: [[#getRoomChar|getRoomChar()]]<br />
<br />
==setRoomCharColor==<br />
;setRoomCharColor(roomId, r, g, b)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set char color to.<br />
* ''r:''<br />
: Red component of room char color (0-255)<br />
* ''g:''<br />
: Green component of room char color (0-255)<br />
* ''b:''<br />
: Blue component of room char color (0-255)<br />
<br />
Sets color for room symbol.<br />
<br />
<syntaxhighlight lang="lua"><br />
setRoomCharColor(2402, 255, 0, 0)<br />
setRoomCharColor(2403, 0, 255, 0)<br />
setRoomCharColor(2404, 0, 0, 255)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
: See also: [[#unsetRoomCharColor|unsetRoomCharColor()]]<br />
<br />
==setRoomCoordinates==<br />
;setRoomCoordinates(roomID, x, y, z)<br />
<br />
:Sets the given room ID to be at the following coordinates visually on the map, where ''z'' is the up/down level. These coordinates are define the location of the room within a particular area (so not globally on the overall map).<br />
<br />
{{note}} 0,0,0 is the center of the map.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$<br />
-- this sets the current room to the supplied coordinates<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
:You can make them relative asa well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^src (\w+)$<br />
<br />
local x,y,z = getRoomCoordinates(previousRoomID)<br />
local dir = matches[2]<br />
<br />
if dir == "n" then<br />
y = y+1<br />
elseif dir == "ne" then<br />
y = y+1<br />
x = x+1<br />
elseif dir == "e" then<br />
x = x+1<br />
elseif dir == "se" then<br />
y = y-1<br />
x = x+1<br />
elseif dir == "s" then<br />
y = y-1<br />
elseif dir == "sw" then<br />
y = y-1<br />
x = x-1<br />
elseif dir == "w" then<br />
x = x-1<br />
elseif dir == "nw" then<br />
y = y+1<br />
x = x-1<br />
elseif dir == "u" or dir == "up" then<br />
z = z+1<br />
elseif dir == "down" then<br />
z = z-1<br />
end<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
==setRoomEnv==<br />
;setRoomEnv(roomID, newEnvID)<br />
<br />
:Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34<br />
</syntaxhighlight><br />
<br />
==setRoomIDbyHash==<br />
;setRoomIDbyHash(roomID, hash)<br />
<br />
:Sets the hash to be associated with the given roomID. See also [[#getRoomIDbyHash|getRoomIDbyHash()]].<br />
<br />
:If the room was associated with a different hash, or vice versa, that association will be superseded.<br />
<br />
==setRoomName==<br />
;setRoomName(roomID, newName)<br />
<br />
:Renames an existing room to a new name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomName(534, "That evil room I shouldn't visit again.")<br />
lockRoom(534, true) -- and lock it just to be safe<br />
</syntaxhighlight><br />
<br />
==setRoomUserData==<br />
;setRoomUserData(roomID, key (as a string), value (as a string))<br />
<br />
:Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store room descriptions...<br />
setRoomUserData(341, "description", "This is a plain-looking room.")<br />
<br />
-- or whenever it's outdoors or not...<br />
setRoomUserData(341, "outdoors", "true")<br />
<br />
-- how how many times we visited that room<br />
local visited = getRoomUserData(341, "visitcount")<br />
visited = (tonumber(visited) or 0) + 1<br />
setRoomUserData(341, "visitcount", tostring(visited))<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))<br />
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)<br />
</syntaxhighlight><br />
<br />
==setRoomWeight==<br />
;setRoomWeight(roomID, weight)<br />
<br />
:Sets a weight to the given roomID. By default, all rooms have a weight of 1 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.<br />
<br />
{{note}} The minimum allowed room weight is 1. <br />
<br />
:To completely avoid a room, make use of [[#lockRoom|lockRoom()]].<br />
<br />
: See also: [[#getRoomWeight|getRoomWeight()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it<br />
</syntaxhighlight><br />
<br />
<br />
==speedwalk==<br />
;speedwalk(dirString, backwards, delay, show)<br />
<br />
:A speedwalking function will work on cardinal+ordinal directions (n, ne, e, etc.) as well as u (for up), d (for down), in and out. It can be called to execute all directions directly after each other, without delay, or with a custom delay, depending on how fast your game allows you to walk. It can also be called with a switch to make the function reverse the whole path and lead you backwards.<br />
<br />
:Call the function by doing: <code>speedwalk("YourDirectionsString", true/false, delaytime, true/false)</code><br />
<br />
:The delaytime parameter will set a delay between each move (set it to 0.5 if you want the script to move every half second, for instance). It is optional: If you don't indicate it, the script will send all direction commands right after each other. (If you want to indicate a delay, you -have- to explicitly indicate true or false for the reverse flag.)<br />
<br />
:The show parameter will determine if the commands sent by this function are shown or hidden. It is optional: If you don't give a value, the script will show all commands sent. (If you want to use this option, you -have- to explicitly indicate true or false for the reverse flag, as well as either some number for the delay or nil if you do not want a delay.)<br />
<br />
:The "YourDirectionsString" contains your list of directions and steps (e.g.: "2n, 3w, u, 5ne"). Numbers indicate the number of steps you want it to walk in the direction specified after it. The directions must be separated by anything other than a letter that can appear in a direction itself. (I.e. you can separate with a comma, spaces, the letter x, etc. and any such combinations, but you cannot separate by the letter "e", or write two directions right next to each other with nothing in-between, such as "wn". If you write a number before every direction, you don't need any further separator. E.g. it's perfectly acceptable to write "3w1ne2e".) The function is not case-sensitive.<br />
<br />
:If your game only has cardinal directions (n,e,s,w and possibly u,d) and you wish to be able to write directions right next to each other like "enu2s3wdu", you'll have to change the pattern slightly. Likewise, if your game has any other directions than n, ne, e, se, s, sw, w, nw, u, d, in, out, the function must be adapted to that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
speedwalk("16d1se1u")<br />
-- Will walk 16 times down, once southeast, once up. All in immediate succession.<br />
<br />
speedwalk("2ne,3e,2n,e")<br />
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.<br />
<br />
speedwalk("IN N 3W 2U W", false, 0.5)<br />
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.<br />
<br />
speedwalk("5sw - 3s - 2n - w", true)<br />
-- Will walk backwards: east, twice south, thrice north, five times northeast. All in immediate succession.<br />
<br />
speedwalk("3w, 2ne, w, u", true, 1.25)<br />
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.<br />
</syntaxhighlight><br />
<br />
{{note}} The probably most logical usage of this would be to put it in an alias. For example, have the pattern ''^/(.+)$'' execute: <code>speedwalk(matches[2], false, 0.7)</code><br />
And have ''^//(.+)$'' execute: <code>speedwalk(matches[2], true, 0.7)</code><br />
Or make aliases like: ''^banktohome$'' to execute <syntaxhighlight lang="lua" inline>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight><br />
<br />
{{note}} The show parameter for this function is available in Mudlet 3.12+<br />
<br />
==stopSpeedwalk==<br />
;stopSpeedwalk()<br />
<br />
:Stops a speedwalk started using [[#speedwalk|speedwalk()]]<br />
: See also: [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]], [[#speedwalk|speedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = stopSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> {err}")<br />
return<br />
end<br />
cecho(f"\n<green>Success:<reset> speedwalk stopped")<br />
</syntaxhighlight><br />
<br />
==unHighlightRoom==<br />
;unHighlightRoom(roomID)<br />
<br />
:Unhighlights a room if it was previously highlighted and restores the rooms original environment color.<br />
: See also: [[#highlightRoom|highlightRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
unHighlightRoom(4534)<br />
</syntaxhighlight><br />
<br />
==unsetRoomCharColor==<br />
;unsetRoomCharColor(roomId)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to unset char color to.<br />
<br />
Removes char color setting from room, back to automatic determination based on room background lightness.<br />
<br />
<syntaxhighlight lang="lua"><br />
unsetRoomCharColor(2031)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==updateMap==<br />
;updateMap()<br />
<br />
:Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.<br />
<br />
: See also: [[#centerview|centerview()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete a some room<br />
deleteRoom(500)<br />
-- now make the map show that it's gone<br />
updateMap()<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Manual:Mapper_Functions&diff=21519Manual:Mapper Functions2024-03-22T05:31:31Z<p>Vadi: /* setRoomChar */ move historical version information into a collapsed menu</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions that manipulate the mapper and its related features.}}<br />
= Mapper Functions =<br />
These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the game you're playing. For a collection of pre-made scripts and general mapper talk, visit the [http://forums.mudlet.org/viewforum.php?f=13 mapper section] of the forums.<br />
<br />
To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:<br />
<syntaxhighlight lang="lua"><br />
mudlet = mudlet or {}; mudlet.mapper_script = true<br />
</syntaxhighlight><br />
<br />
==addAreaName==<br />
;areaID = addAreaName(areaName)<br />
<br />
:Adds a new area name and returns the new (positive) area ID for the new name. If the name already exists, older versions of Mudlet returned -1 though since 3.0 the code will return ''nil'' and an error message.<br />
: See also: [[#deleteArea|deleteArea()]], [[#addRoom|addRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local newId, err = addAreaName("My House")<br />
<br />
if newId == nil or newId < 1 or err then<br />
echo("That area name could not be added - error is: ".. err.."\n")<br />
else<br />
cecho("<green>Created new area with the ID of "..newId..".\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==addCustomLine==<br />
;addCustomLine(roomID, id_to, direction, style, color, arrow)<br />
: See also: [[#getCustomLines|getCustomLines()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to attach the custom line to.<br />
* ''id_to:''<br />
: EITHER: a room Id number, of a room on same area who's x and y coordinates are used as the other end of a SINGLE segment custom line (it does NOT imply that is what the exit it represent goes to, just the location of the end of the line);<br />
: OR: a table of sets of THREE (x,y and z) coordinates in that order, x and y can be decimals, z is an integer ('''and must be present and be the same for all points on the line''', though it is irrelevant to what is produced as the line is drawn on the same z-coordinate as the room that the line is attached to!)<br />
* ''direction:'' a string to associate the line with a valid exit direction, "n", "ne", "e", "se", "s", "sw", "w", "nw", "up", "down", "in" or "out" or a special exit (before Mudlet 3.17 this was case-sensitive and cardinal directions had to be uppercase).<br />
* ''style:'' a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.<br />
* ''color:'' a table of three integers between 0 and 255 as the custom line color as the red, green and blue components in that order.<br />
* ''arrow:'' a boolean which if true will set the custom line to have an arrow on the end of the last segment.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- create a line from roomid 1 to roomid 2<br />
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)<br />
<br />
addCustomLine(1, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
</syntaxhighlight><br />
<br />
A bigger example that'll create a new area and the room in it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local areaid = addAreaName("my first area")<br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
setRoomArea(newroomid, "my first area")<br />
setRoomCoordinates(newroomid, 0, 0, 0)<br />
<br />
local otherroomid = createRoomID()<br />
addRoom(otherroomid)<br />
setRoomArea(otherroomid, "my first area")<br />
setRoomCoordinates(otherroomid, 0, 5, 0)<br />
<br />
addSpecialExit(newroomid, otherroomid, "climb Rope")<br />
addCustomLine(newroomid, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
<br />
centerview(newroomid)<br />
</syntaxhighlight><br />
<br />
==addMapEvent==<br />
;addMapEvent(uniquename, event name, parent, display name, arguments)<br />
<br />
:Adds a new entry to an existing mapper right-click entry. You can add one with addMapMenu. If there is no display name, it will default to the unique name (which otherwise isn't shown and is just used to differentiate this entry from others). ''event name'' is the Mudlet event that will be called when this is clicked on, and ''arguments'' will be passed to the handler function.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn") <br />
</syntaxhighlight><br />
The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.<br />
<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Room type")<br />
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")<br />
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")<br />
<br />
function onMapMarkSelectedRooms(event, markRoomType)<br />
local selectedRooms = getMapSelection()["rooms"]<br />
for i, val in ipairs(selectedRooms) do<br />
if markRoomType == "markRoomsAsDeathTrap" then<br />
local r, g, b = unpack(color_table.black)<br />
--death trap<br />
setRoomEnv(val, 300)<br />
--death traps Env<br />
setCustomEnvColor(300, r, g, b, 255)<br />
setRoomChar(val, "☠️")<br />
lockRoom(val, true)<br />
elseif markRoomType == "markRoomsAsOneRoom" then<br />
local r, g, b = unpack(color_table.LightCoral)<br />
--single-pass<br />
setRoomEnv(val, 301)<br />
--one room Env<br />
setCustomEnvColor(301, r, g, b, 255)<br />
setRoomChar(val, "🚹")<br />
end<br />
end<br />
updateMap()<br />
end<br />
<br />
registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")<br />
</syntaxhighlight><br />
This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"<br />
<br />
==addMapMenu==<br />
;addMapMenu(uniquename, parent, display name)<br />
<br />
:Adds a new submenu to the right-click menu that opens when you right-click on the mapper. You can then add more submenus to it, or add entries with [[#addMapEvent|addMapEvent()]].<br />
: See also: [[#addMapEvent|addMapEvent()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will create a menu named: Favorites.<br />
addMapMenu("Favorites")<br />
<br />
-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.<br />
addMapMenu("Favorites1234343", "Favorites", "More Favorites") <br />
</syntaxhighlight><br />
<br />
==addRoom==<br />
;addRoom(roomID)<br />
<br />
:Creates a new room with the given ID, returns true if the room was successfully created. <br />
<br />
{{note}} If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with [[#createRoomID|createRoomID()]] and associating your room IDs with Mudlets via [[#setRoomIDbyHash|setRoomIDbyHash()]] and [[#getRoomIDbyHash|getRoomIDbyHash()]]. The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge.<br />
{{note}} Creating your own mapping script? Check out more [[Manual:Mapper#Making_your_own_mapping_script|information here]].<br />
<br />
: See also: [[#createRoomID|createRoomID()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
</syntaxhighlight><br />
<br />
==addSpecialExit==<br />
;addSpecialExit(roomIDFrom, roomIDTo, moveCommand)<br />
<br />
:Creates a one-way from one room to another, that will use the given command for going through them.<br />
<br />
: See also: [[#clearSpecialExits|clearSpecialExits()]], [[#removeSpecialExit|removeSpecialExit()]], [[#setExit|setExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command<br />
addSpecialExit(1, 2, "pull rope")<br />
</syntaxhighlight><br />
<br />
Example in an alias:<br />
<syntaxhighlight lang="lua"><br />
-- sample alias pattern: ^spe (\d+) (.*?)$<br />
-- currentroom is your current room ID in this example<br />
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])<br />
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])<br />
centerview(currentroom)<br />
</syntaxhighlight><br />
<br />
==auditAreas==<br />
;auditAreas()<br />
<br />
: Initiates a consistency check on the whole map: All rooms, areas, and their composition. This is also done automatically whenever you first open your map, so probably seldom necessary to do manually. Will output findings to screen and/or logfile for later review.<br />
<br />
: See also: [[#saveMap|saveMap()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
==centerview==<br />
;centerview (roomID)<br />
<br />
:Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.<br />
<br />
: See also: [[#getPlayerRoom|getPlayerRoom()]], [[#updateMap|updateMap()]]<br />
<br />
==clearAreaUserData==<br />
;clearAreaUserData(areaID)<br />
<br />
; Parameter<br />
* areaID - ID number for area to clear.<br />
<br />
:Clears all user data from a given area. Note that this will not touch the room user data.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#clearRoomUserData|clearRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearAreaUserData(34))<br />
-- I did have data in that area, so it returns:<br />
true<br />
<br />
display(clearAreaUserData(34))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearAreaUserDataItem==<br />
;clearAreaUserDataItem(areaID, key)<br />
<br />
:Removes the specific key and value from the user data from a given area.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#clearAreaUserData|clearAreaUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
true<br />
<br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapSelection==<br />
;clearMapSelection()<br />
<br />
:Clears any selected rooms from the map (i.e. they are highlighted in orange).<br />
<br />
:Returns true if rooms are successfully cleared, false if nothing selected or cleared.<br />
<br />
: See also [[#getMapSelection|getMapSelection()]]<br />
<br />
==clearMapUserData==<br />
;clearMapUserData()<br />
<br />
:Clears all user data stored for the map itself. Note that this will not touch the area or room user data.<br />
<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserData|clearAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearMapUserData())<br />
-- I did have user data stored for the map, so it returns:<br />
true<br />
<br />
display(clearMapUserData())<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapUserDataItem==<br />
;clearMapUserDataItem(mapID, key)<br />
<br />
:Removes the specific key and value from the user data from the map user data.<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearMapUserData|clearMapUserData()]], [[#clearAreaRoomUserData|clearAreaRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
last_modified = "1483228799"<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
true<br />
<br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearRoomUserData==<br />
;clearRoomUserData(roomID)<br />
<br />
:Clears all user data from a given room.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{note}} Returns a boolean true if any data was removed from the specified room and false if there was nothing to erase since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearRoomUserData(3441))<br />
-- I did have data in that room, so it returns:<br />
true<br />
<br />
display(clearRoomUserData(3441))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearRoomUserDataItem==<br />
;clearRoomUserDataItem(roomID, key)<br />
<br />
:Removes the specific key and value from the user data from a given room.<br />
:Returns a boolean true if data was found against the give key in the user data for the given room and it is removed, will return false if exact key not present in the data. Returns nil if the room for the roomID not found.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
true<br />
<br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearSpecialExits==<br />
;clearSpecialExits(roomID) <br />
<br />
:Removes all special exits from a room.<br />
: See also: [[#addSpecialExit|addSpecialExit()]], [[#removeSpecialExit|removeSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
clearSpecialExits(1337)<br />
<br />
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example<br />
echo("All special exits successfully cleared from 1337.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==closeMapWidget==<br />
;closeMapWidget()<br />
:closes (hides) the map window (similar to clicking on the map icon)<br />
<br />
{{MudletVersion|4.7}}<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
==connectExitStub==<br />
;connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])<br />
<br />
:Connects existing rooms with matching exit stubs. If you only give it a roomID and a direction, it'll work out which room should be linked to it that has an appropriate opposite exit stub and is located in the right direction. You can also just specify from and to room IDs, and it'll smartly use the right direction to link in. Lastly, you can specify all three arguments - fromID, toID and the direction (in that order) if you'd like to be explicit, or use [[#setExit|setExit()]] for the same effect.<br />
<br />
;Parameters<br />
* ''fromID:''<br />
: Room ID to set the exit stub in.<br />
* ''direction:''<br />
: You can either specify the direction to link the room in, and/or a specific room ID (see below). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
* ''toID:''<br />
: The room ID to link this room to. If you don't specify it, the mapper will work out which room should be logically linked.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- try and connect all stubs that are in a room<br />
local stubs = getExitStubs(roomID)<br />
if stubs then<br />
for i,v in pairs(stubs) do<br />
connectExitStub(roomID, v)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==createMapLabel==<br />
;labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])<br />
<br />
:Creates a text label on the map at given coordinates, with the given background and foreground colors. It can go above or below the rooms, scale with zoom or stay a static size. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a script can reduce the size of the saved map somewhat. It returns a label ID that you can use later for deleting it.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
<br />
: See also: [[#getMapLabel|getMapLabel()]], [[#getMapLabels|getMapLabels()]], [[#deleteMapLabel|deleteMapLabel]], [[#createMapImageLabel|createMapImageLabel()]]<br />
<br />
{{note}} Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID where to put the label.<br />
* ''text:''<br />
: The text to put into the label. To get a multiline text label add a '\n' between the lines.<br />
* ''posX, posY, posZ:''<br />
: Position of the label in (floating point numbers) room coordinates.<br />
* ''fgRed, fgGreen, fgBlue:''<br />
: Foreground color or text color of the label.<br />
* ''bgRed, bgGreen, bgBlue:''<br />
: Background color of the label.<br />
* ''zoom:''<br />
: (optional) Zoom factor of the label if noScaling is false. Higher zoom will give higher resolution of the text and smaller size of the label. Default is 30.0.<br />
* ''fontSize:''<br />
: (optional, but needed if zoom is provided) Size of the font of the text. Default is 50.<br />
* ''showOnTop:''<br />
: (optional) If true the label will be drawn on top of the rooms and if it is false the label will be drawn as a background, defaults to true if not given.<br />
* ''noScaling:''<br />
: (optional) If true the label will have the same size when you zoom in and out in the mapper, If it is false the label will scale when you zoom the mapper, defaults to true if not given.<br />
* ''fontName:''<br />
: (optional) font name to use.<br />
* ''foregroundTransparency''<br />
: (optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.<br />
* ''backgroundTransparency''<br />
: (optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.<br />
* ''temporary''<br />
: (optional, from Mudlet version 4.17.0) if true does not save the image that the label makes in map save files, defaults to false if not given, or for prior versions of Mudlet.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area<br />
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB<br />
-- zoom is only relevant when when you're using a label of a static size, so we use 0<br />
-- and we use a font size of 20 for our label, which is a small medium compared to the map<br />
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)<br />
<br />
-- to create a multi line text label we add '\n' between lines<br />
-- the position is placed somewhat to the northeast of the center of the map<br />
-- this label will be scaled as you zoom the map.<br />
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)<br />
<br />
local x,y,z = getRoomCoordinates(getPlayerRoom())<br />
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)<br />
</syntaxhighlight><br />
<br />
==createMapImageLabel==<br />
;labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])<br />
<br />
:Creates an image label on the map at the given coordinates, with the given dimensions and zoom. You might find the default room and image size correlation to be too big - try reducing the width and height of the image then, while also zooming in the same amount. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a external file available when the map file is loaded, can avoid expanding the size of the saved map considerably.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
: See also: [[#createMapLabel|createMapLabel]], [[#deleteMapLabel|deleteMapLabel]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- 138 is our pretend area ID<br />
-- next, inside [[]]'s, is the exact location of our image<br />
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map<br />
-- 482 is the width of the image - we divide it by 100 to scale it down, and then we'll zoom it by 100 - making the image take up about 4 rooms in width then<br />
-- 555 is the original height of the image<br />
-- 100 is how much we zoom it by, 1 would be no zoom<br />
-- false to make it go below our rooms<br />
-- (from 4.17.0) true to not save the label's image in the map file afterwards<br />
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)<br />
</syntaxhighlight><br />
<br />
==createMapper==<br />
;createMapper([name of userwindow], x, y, width, height)<br />
<br />
:Creates a miniconsole window for the mapper to render in, the with the given dimensions. You can only create one mapper at a time, and it is not currently possible to have a label on or under the mapper - otherwise, clicks won't register.<br />
<br />
{{note}} ''name of userwindow'' available in Mudlet 4.6.1+<br />
<br />
{{Note}} If this command is ''not'' used then clicking on the Main Toolbar's '''Map''' button will create a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Map''' button will toggle between showing and hiding the map whether it was created using the ''createMapper'' function or as a dock-able widget.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet<br />
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- another example:<br />
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})<br />
<br />
local mapper = Geyser.Mapper:new({<br />
name = "mapper",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, main)<br />
</syntaxhighlight><br />
<br />
==createRoomID==<br />
;usableId = createRoomID([minimumStartingRoomId])<br />
<br />
:Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs. <br />
<br />
;Parameters<br />
* ''minimumStartingRoomId'' (optional, available in Mudlet 3.0+):<br />
: If provided, specifies a roomID to start searching for an empty one at, instead of 1. Useful if you'd like to ensure certain areas have specific room number ranges, for example. If you you're working with a huge map, provide the last used room ID to this function for an available roomID to be found a lot quicker.<br />
<br />
: See also: [[#addRoom|addRoom()]]<br />
<br />
==deleteArea==<br />
;deleteArea(areaID or areaName)<br />
<br />
:Deletes the given area and all rooms in it. Returns ''true'' on success or ''nil'' + ''error message'' otherwise.<br />
: See also: [[#addAreaName|addAreaName()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to delete, or:<br />
* ''areaName'' (available in Mudlet 3.0+):<br />
: Area name to delete.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete by areaID<br />
deleteArea(23)<br />
-- or since Mudlet 3.0, by area name<br />
deleteArea("Big city")<br />
</syntaxhighlight><br />
<br />
==deleteMap==<br />
;deleteMap()<br />
<br />
Deletes the entire map. This may be useful whilst initially setting up a mapper package for a new Game to clear faulty map data generated up to this point.<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
{{MudletVersion|4.14.0}}<br />
<br />
;Returns<br />
:''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result - which will be the "blank" screen with a warning message of the form ''"No rooms in the map - load another one, or start mapping from scratch to begin."''<br />
<br />
{{note}} Prior to the introduction of this function, the recommended method to achieve the same result was to use [[#loadMap|loadMap()]] with a non-existent file-name, such as ''"_"'' however that would also cause an ''"[ ERROR ]"'' type message to appear on the profile's main console.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMap()<br />
</syntaxhighlight><br />
<br />
==deleteMapLabel==<br />
;deleteMapLabel(areaID, labelID)<br />
<br />
:Deletes a map label from a specific area.<br />
: See also: [[#createMapLabel|createMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMapLabel(50, 1)<br />
</syntaxhighlight><br />
<br />
==deleteRoom==<br />
;deleteRoom(roomID)<br />
<br />
:Deletes an individual room, and unlinks all exits leading to and from it.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteRoom(335)<br />
</syntaxhighlight><br />
<br />
==disableMapInfo==<br />
;disableMapInfo(label)<br />
<br />
Disable the particular map info - same as toggling off checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be disabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==enableMapInfo==<br />
;enableMapInfo(label)<br />
<br />
Enable the particular map info - same as toggling on checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be enabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#disableMapInfo|disableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==getAllAreaUserData==<br />
;dataTable = getAllAreaUserData(areaID)<br />
<br />
:Returns all the user data items stored in the given area ID; will return an empty table if there is no data stored or nil if there is no such area with that ID.<br />
<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
--might result in:--<br />
{<br />
country = "Andor",<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllMapUserData==<br />
;dataTable = getAllMapUserData()<br />
<br />
:Returns all the user data items stored at the map level; will return an empty table if there is no data stored.<br />
<br />
: See also: [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
--might result in:--<br />
{<br />
description = [[This map is about so and so game]],<br />
author = "Bob",<br />
["last updated"] = "December 5, 2020"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllRoomEntrances==<br />
;exitsTable = getAllRoomEntrances(roomID)<br />
<br />
:Returns an indexed list of normal and special exits leading into this room. In case of two-way exits, this'll report exactly the same rooms as [[#getRoomExits|getRoomExits()]], but this function has the ability to pick up one-way exits coming into the room as well.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- print the list of rooms that have exits leading into room 512<br />
for _, roomid in ipairs(getAllRoomEntrances(512)) do <br />
print(roomid)<br />
end<br />
</syntaxhighlight><br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
==getAllRoomUserData==<br />
;dataTable = getAllRoomUserData(roomID)<br />
<br />
:Returns all the user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
;See also: [[#getRoomUserDataKeys|getRoomUserDataKeys()]] - for a related command that only returns the data keys.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
--might result in:--<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
</syntaxhighlight><br />
<br />
==getAreaExits==<br />
;roomTable = getAreaExits(areaID, showExits)<br />
<br />
: Returns a table (indexed or key-value) of the rooms in the given area that have exits leading out to other areas - that is, border rooms.<br />
<br />
;See also: [[#setExit|setExit()]], [[#getRoomExits|getRoomExits()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to list the exits for.<br />
* ''showExits:''<br />
: Boolean argument, if true then the exits that lead out to another area will be listed for each room.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- list all border rooms for area 44:<br />
getAreaExits(44)<br />
<br />
-- returns:<br />
--[[<br />
{<br />
7091,<br />
10659,<br />
11112,<br />
11122,<br />
11133,<br />
11400,<br />
12483,<br />
24012<br />
}<br />
]]<br />
<br />
-- list all border rooms for area 44, and the exits within them that go out to other areas:<br />
getAreaExits(44, true)<br />
--[[<br />
{<br />
[12483] = {<br />
north = 27278<br />
},<br />
[11122] = {<br />
["enter grate"] = 14551<br />
},<br />
[11112] = {<br />
["enter grate"] = 14829<br />
},<br />
[24012] = {<br />
north = 22413<br />
},<br />
[11400] = {<br />
south = 10577<br />
},<br />
[11133] = {<br />
["enter grate"] = 15610<br />
},<br />
[7091] = {<br />
down = 4411<br />
},<br />
[10659] = {<br />
["enter grate"] = 15510<br />
}<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
==getAreaRooms==<br />
;getAreaRooms(area id)<br />
<br />
:Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or ''nil'' if no such area exists. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- using the sample findAreaID() function defined in the getAreaTable() example, <br />
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID<br />
function echoRoomList(areaname)<br />
local id, msg = findAreaID(areaname)<br />
if id then<br />
local roomlist, endresult = getAreaRooms(id), {}<br />
<br />
-- obtain a room list for each of the room IDs we got<br />
for _, id in pairs(roomlist) do<br />
endresult[id] = getRoomName(id)<br />
end<br />
<br />
-- now display something half-decent looking<br />
cecho(string.format(<br />
"List of all rooms in %s (%d):\n", msg, table.size(endresult)))<br />
<br />
for roomid, roomname in pairs(endresult) do<br />
cecho(string.format(<br />
"%6s: %s\n", roomid, roomname))<br />
end<br />
elseif not id and msg then<br />
echo("ID not found; " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTable==<br />
;areaTable = getAreaTable()<br />
<br />
:Returns a key(area name)-value(area id) table with all known areas and their IDs. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
;See also: [[#getAreaTableSwap|getAreaTableSwap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example function that returns the area ID for a given area<br />
<br />
function findAreaID(areaname)<br />
local list = getAreaTable()<br />
<br />
-- iterate over the list of areas, matching them with substring match. <br />
-- if we get match a single area, then return it's ID, otherwise return<br />
-- 'false' and a message that there are than one are matches<br />
local returnid, fullareaname<br />
for area, id in pairs(list) do<br />
if area:find(areaname, 1, true) then<br />
if returnid then return false, "more than one area matches" end<br />
returnid = id; fullareaname = area<br />
end<br />
end<br />
<br />
return returnid, fullareaname<br />
end<br />
<br />
-- sample use:<br />
local id, msg = findAreaID("blahblah")<br />
if id then<br />
echo("Found a matching ID: " .. id)<br />
elseif not id and msg then<br />
echo("ID not found: " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTableSwap==<br />
;areaTable = getAreaTableSwap()<br />
<br />
:Returns a key(area id)-value(area name) table with all known areas and their IDs. Unlike getAreaTable which won't show you all areas with the same name by different IDs, this function will. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
==getAreaUserData==<br />
;dataValue = getAreaUserData(areaID, key)<br />
<br />
:Returns a specific data item stored against the given key for the given area ID number. This is very like the corresponding Room User Data command but intended for per area rather than for per room data (for storage of data relating to the whole map see the corresponding Map User Data commands.) <br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or a Lua ''nil'' and an error message if the key is not present in the Area User Data for the given Area ID. Use [[#setAreaUserData|setAreaUserData()]] function for storing the user data.<br />
<br />
;See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAreaUserData(34, "country"))<br />
-- might produce --<br />
"Andor"<br />
</syntaxhighlight><br />
<br />
==getCustomEnvColorTable==<br />
;envcolors = getCustomEnvColorTable()<br />
<br />
:Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
{<br />
envid1 = {r, g, b, alpha},<br />
envid2 = {r, g, b, alpha}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines==<br />
;lineTable = getCustomLines(roomID)<br />
: See also: [[#addCustomLine|addCustomLine()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Returns a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the custom line details of.<br />
<br />
{{MudletVersion|3.0.}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = {<br />
b = 0,<br />
g = 128,<br />
r = 128<br />
},<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = {<br />
{<br />
y = 9.5,<br />
x = 4.5<br />
},<br />
{<br />
y = 9.5,<br />
x = 6<br />
},<br />
[0] = {<br />
y = 5.5,<br />
x = 4.5<br />
}<br />
}<br />
},<br />
N = {<br />
attributes = {<br />
color = {<br />
b = 255,<br />
g = 255,<br />
r = 0<br />
},<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = {<br />
[0] = {<br />
y = 27,<br />
x = -3<br />
}<br />
}<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines1==<br />
;lineTable = getCustomLines1(roomID)<br />
This is a replacement for ''getCustomLines(...)'' that outputs the tables for the coordinates for the points on the custom line in an order and format that can be fed straight back into an ''addCustomLine(...)'' call; similarly the color parameters are also reported in the correct format to also be reused in the same manner. This function is intended to make it simpler for scripts to manipulate such lines.<br />
:See also: [[Manual:Mapper_Functions#addCustomLine|addCustomLine()]], [[Manual:Mapper_Functions#removeCustomLine|removeCustomLine()]], [[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]<br />
{{MudletVersion| 4.16}}<br />
<br />
;Parameters<br />
* ''roomID:''<br />
:Room ID to return the custom line details of.<br />
<br />
;Returns<br />
:a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines1(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = { 128, 128, 0 },<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } } <br />
},<br />
N = {<br />
attributes = {<br />
color = { 0, 255, 255 },<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = { { -3, 27, 3 } }<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getDoors==<br />
;doors = getDoors(roomID)<br />
<br />
:Returns a key-value table with the cardinal direction as the key and the door value as a number. If there are no doors in a room, it returns an empty table.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to check for doors in.<br />
<br />
: See also: [[#setDoor|setDoor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example that displays possible doors in room 2334<br />
local doors = getDoors(2334)<br />
<br />
if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end<br />
<br />
local door_status = {"open", "closed", "locked"}<br />
<br />
for direction, door in pairs(doors) do<br />
cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")<br />
end<br />
</syntaxhighlight><br />
<br />
==getExitStubs==<br />
;stubs = getExitStubs(roomid)<br />
<br />
:Returns an indexed table (starting at 0) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#connectExitStub|connectExitStub()]], [[#getExitStubs1|getExitStubs1()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
local stubs = getExitStubs(6)<br />
for i = 0, #stubs do print(stubs[i]) end<br />
</syntaxhighlight><br />
<br />
{{note}} Previously would throw a lua error on non-existent room - now returns nil plus error message (as does other run-time errors) - previously would return just a nil on NO exit stubs but now returns a notification error message as well, to aide disambiguation of the nil value.<br />
<br />
==getExitStubs1==<br />
;stubs = getExitStubs1(roomid)<br />
<br />
:Returns an indexed table (starting at 1) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. As this function starts indexing from 1 as it is default in Lua, you can use ipairs() to iterate over the results.<br />
<br />
; See also: [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end<br />
</syntaxhighlight><br />
<br />
==getExitWeights==<br />
;weights = getExitWeights(roomid)<br />
<br />
:Returns a key-value table of the exit weights that a room has, with the direction or special exit as a key and the value as the exit weight. If a weight for a direction wasn't yet set, it won't be listed.<br />
<br />
;Parameters<br />
* ''roomid:''<br />
: Room ID to view the exit weights in.<br />
<br />
: See also: [[#setExitWeight|setExitWeight()]]<br />
<br />
==getGridMode==<br />
;TrueOrFalse = getGridMode(areaID)<br />
<br />
:Use this to see, if a specific area has grid/wilderness view mode set. This way, you can also calculate from a script, how many grid areas a map has got in total.<br />
<br />
{{MudletVersion|3.11}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID (number) to view the grid mode of.<br />
<br />
: See also: [[#setGridMode|setGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getGridMode(55)<br />
-- will return: false<br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
getGridMode(55)<br />
-- will return: true<br />
</syntaxhighlight><br />
<br />
==getMapEvents==<br />
; mapevents = getMapEvents()<br />
<br />
: Returns a list of map events currently registered. Each event is a dictionary with the keys ''uniquename'', ''parent'', ''event name'', ''display name'', and ''arguments'', which correspond to the arguments of ''addMapEvent()''.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")<br />
<br />
local mapEvents = getMapEvents()<br />
for _, event in ipairs(mapEvents) do<br />
echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.3}}<br />
<br />
==getMapLabel==<br />
;labelinfo = getMapLabel(areaID, labelID or labelText)<br />
<br />
:Returns a key-value table describing that particular label in an area. Keys it contains are the ''X'', ''Y'', ''Z'' coordinates, ''Height'' and ''Width'', ''BgColor'', ''FgColor'', ''Pixmap'', and the ''Text'' it contains. If the label is an image label, then ''Text'' will be set to the ''no text'' string.<br />
<br />
:''BgColor'' and ''FgColor'' are tables with ''r'',''g'',''b'' keys, each holding ''0-255'' color component value.<br />
<br />
:''Pixmap'' is base64 encoded image of label.<br />
<br />
{{note}} ''BgColor'', ''FgColor'', ''Pixmap'' are available in Mudlet 4.11+<br />
<br />
;Parameters <br />
* ''areaID:'' areaID from which to retrieve label<br />
* ''labelID:'' labelID (''getMapLabels'' return table key) or labelText (exact match)<br />
<br />
See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabels|getMapLabels()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua getMapLabels(52)<br />
{<br />
"no text",<br />
[0] = "test"<br />
}<br />
<br />
lua getMapLabel(52, 0)<br />
{<br />
Y = -2,<br />
X = -8,<br />
Z = 11,<br />
Height = 3.9669418334961,<br />
Text = "test",<br />
Width = 8.6776866912842,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
<br />
lua getMapLabel(52, "no text")<br />
{<br />
Y = 8,<br />
X = -15,<br />
Z = 11,<br />
Height = 7.2520666122437,<br />
Text = "no text"<br />
Width = 11.21900844574,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapLabels==<br />
;arealabels = getMapLabels(areaID)<br />
<br />
:Returns an indexed table (that starts indexing from 0) of all of the labels in the area, plus their label text. You can use the label id to [[#deleteMapLabel|deleteMapLabel()]] it.<br />
:If there are no labels in the area at all, it will return an empty table.<br />
<br />
: See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabel|getMapLabel()]], [[#deleteMapLabel|deleteMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapLabels(43))<br />
table {<br />
0: ''<br />
1: 'Waterways'<br />
}<br />
<br />
deleteMapLabel(43, 0)<br />
display(getMapLabels(43))<br />
table {<br />
1: 'Waterways'<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapMenus==<br />
;getMapMenus()<br />
<br />
:Returns a table with the available map menus as key-value in the format of <code>map menu - parent item</code>. If an item is positioned at the menu's top-level, the value will say <code>top-level</code>.<br />
:If you haven't opened a map yet, getMapMenus() will return nil+error message. If you don't have any map labels yet, an empty table <code>{}</code> is returned.<br />
<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- given the following menu structure:<br />
top-level<br />
menu1<br />
menu1.1<br />
action1.1.1<br />
menu1.2<br />
action1.2.1<br />
menu2<br />
<br />
getMapMenus() -- will return:<br />
{<br />
menu2 = "top-level",<br />
menu1.2 = "menu1",<br />
menu1.1 = "menu1",<br />
menu1 = "top-level"<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapSelection==<br />
; getMapSelection()<br />
<br />
:Returns a table containing details of the current mouse selection in the 2D mapper.<br />
<br />
:Reports on one or more rooms being selected (i.e. they are highlighted in orange).<br />
<br />
:The contents of the table will vary depending on what is currently selected. If the selection is of map rooms then there will be keys of ''center'' and ''rooms'': the former will indicates the center room (the one with the yellow cross-hairs) if there is more than one room selected or the only room if there is only one selected (there will not be cross-hairs in that case); the latter will contain a list of the one or more rooms.<br />
<br />
; Example - several rooms selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5011,<br />
5012,<br />
5013,<br />
5014,<br />
5018,<br />
5019,<br />
5020<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - one room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5013<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - no or something other than a room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==getMapUserData==<br />
;getMapUserData( key )<br />
<br />
;Parameters<br />
* ''key:''<br />
: string used as a key to select the data stored in the map as a whole.<br />
<br />
:Returns the user data item (string); will return a nil+error message if there is no data with such a key in the map data.<br />
<br />
: See also: [[#getAllMapUserData|getAllMapUserData()]], [[#setMapUserData|setMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapUserData("last updated"))<br />
--might result in:--<br />
"December 5, 2020"<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getMapZoom==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''4.17.0''''' also with the option to get the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet remembering the zoom level last used for each area and with the revision of the ''setMapZoom()'' function to also take an areaID to work on instead of the current area being viewed in the map.<br />
<br />
:See also: [[Manual:Mapper_Functions#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| 4.17.0}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is ''3.0'' and the initial value - and what prior Mudlet versions started each session with - is ''20.0''.<br />
<br />
==getPath==<br />
;getPath(roomID from, roomID to)<br />
<br />
:Returns a boolean true/false if a path between two room IDs is possible. If it is, the global ''speedWalkDir'' table is set to all of the directions that have to be taken to get there, and the global ''speedWalkPath'' table is set to all of the roomIDs you'll encounter on the way, and as of 3.0, ''speedWalkWeight'' will return all of the room weights. Additionally returns the total cost (all weights added up) of the path after the boolean argument in 3.0.<br />
<br />
<br />
: See also: [[Manual:Lua_Functions#translateTable|translateTable()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if we can go to room 155 from room 34 - if yes, go to it<br />
if getPath(34,155) then<br />
gotoRoom(155)<br />
else<br />
echo("\nCan't go there!")<br />
end<br />
</syntaxhighlight><br />
<br />
==getPlayerRoom==<br />
;getPlayerRoom()<br />
<br />
:Returns the current player location as set by [[#centerview|centerview()]].<br />
<br />
: See also: [[#centerview|centerview]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("We're currently in " .. getRoomName(getPlayerRoom()))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.14}}<br />
<br />
==getRoomArea==<br />
;getRoomArea(roomID)<br />
<br />
:Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by [[#getAreaTable | getAreaTable()]] function, or use the [[#getRoomAreaName |getRoomAreaName()]] function.<br />
<br />
{{note}} If the room ID does not exist, this function will raise an error.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Area ID of room #100 is: "..getRoomArea(100))<br />
<br />
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))<br />
</syntaxhighlight><br />
<br />
==getRoomAreaName==<br />
;getRoomAreaName(areaID or areaName)<br />
<br />
:Returns the area name for a given area id; or the area id for a given area name.<br />
<br />
{{note}} Despite the name, this function will not return the area name for a given ''room'' id (or room name) directly. However, renaming or revising it would break existing scripts.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))<br />
</syntaxhighlight><br />
<br />
<br />
==getRoomChar==<br />
;getRoomChar(roomID)<br />
<br />
:Returns the single ASCII character that forms the ''symbol'' for the given room id.<br />
<br />
: '''Since Mudlet version 3.8 :''' this facility has been extended:<br />
: Returns the string (UTF-8) that forms the ''symbol'' for the given room id; this may have been set with either [[#setRoomChar|setRoomChar()]] or with the ''symbol'' (was ''letter'' in prior versions) context menu item for rooms in the 2D Map.<br />
<br />
==getRoomCharColor==<br />
;r,g,b = getRoomCharColor(roomID)<br />
<br />
:Returns the color of the Room Character as a set of r,g,b color coordinates.<br />
<br />
;See also: [[Manual:Lua_Functions#setRoomCharColor|setRoomCharColor()]], [[Manual:Lua_Functions#getRoomChar|getRoomChar()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room ID to get the room character color from<br />
<br />
;Returns <br />
* The color as 3 separate numbers, red, green, and blue from 0-255<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0<br />
local r,g,b = getRoomCharColor(12345)<br />
decho(f"Room Character for room 12345 is <{r},{g},{b}>this color.<r> It is made up of <{r},0,0>{r} red<r>, <0,{g},0>{g} green<r>, <0,0,{b}> {b} blue<r>.\")<br />
</syntaxhighlight><br />
<br />
==getRoomCoordinates==<br />
;x,y,z = getRoomCoordinates(roomID)<br />
<br />
:Returns the room coordinates of the given room ID.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local x,y,z = getRoomCoordinates(roomID)<br />
echo("Room Coordinates for "..roomID..":")<br />
echo("\n X:"..x)<br />
echo("\n Y:"..y)<br />
echo("\n Z:"..z)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- A quick function that will find all rooms on the same z-position in an area; this is useful if, say, you want to know what all the same rooms on the same "level" of an area is.<br />
function sortByZ(areaID, zval)<br />
local area = getAreaRooms(areaID)<br />
local t = {}<br />
for _, id in ipairs(area) do<br />
local _, _, z = getRoomCoordinates(id)<br />
if z == zval then<br />
table.insert(t, id)<br />
end<br />
end<br />
return t<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomEnv==<br />
;envID = getRoomEnv(roomID)<br />
<br />
:Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function checkID(id)<br />
echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))<br />
end<br />
</syntaxhighlight><br />
<br />
== getRoomExits ==<br />
;getRoomExits (roomID)<br />
:Returns the currently known non-special exits for a room in an key-index form: ''exit = exitroomid''.<br />
<br />
: See also: [[#getSpecialExits|getSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
table {<br />
'northwest': 80<br />
'east': 78<br />
}<br />
</syntaxhighlight><br />
<br />
Here's a practical example that queries the rooms around you and searched for one of the water environments (the number would depend on how it was mapped):<br />
<br />
<syntaxhighlight lang="lua"><br />
local exits = getRoomExits(mycurrentroomid)<br />
for direction,num in pairs(exits) do<br />
local env_num = getRoomEnv(num)<br />
if env_num == 22 or env_num == 20 or env_num == 30 then<br />
print("There's water to the "..direction.."!")<br />
end<br />
end</syntaxhighlight><br />
<br />
==getRoomHashByID==<br />
;getRoomHashByID(roomID)<br />
<br />
:Returns a room hash that is associated with a given room ID in the mapper. This is primarily for games that make use of hashes instead of room IDs. It may be used to share map data while not sharing map itself. ''nil'' is returned if no room is not found.<br />
<br />
: See also: [[#getRoomIDbyHash|getRoomIDbyHash()]]<br />
{{MudletVersion|3.13.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
for id,name in pairs(getRooms()) do<br />
local h = getRoomUserData(id, "herbs")<br />
if h ~= "" then<br />
echo(string.format([[["%s"] = "%s",]], getRoomHashByID(id), h))<br />
echo("\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomIDbyHash==<br />
;roomID = getRoomIDbyHash(hash)<br />
<br />
:Returns a room ID that is associated with a given hash in the mapper. This is primarily for games that make use of hashes instead of room IDs (like [http://avalon.mud.de/index.php?enter=1 Avalon.de]). ''-1'' is returned if no room ID matches the hash.<br />
<br />
: See also: [[#getRoomHashByID|getRoomHashByID()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177<br />
local id = getRoomIDbyHash("5dfe55b0c8d769e865fd85ba63127fbc")<br />
if id == -1 then <br />
id = createRoomID()<br />
setRoomIDbyHash(id, "5dfe55b0c8d769e865fd85ba63127fbc")<br />
addRoom(id)<br />
setRoomCoordinates(id, 0, 0, -1)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomName==<br />
;getRoomName(roomID)<br />
<br />
:Returns the room name for a given room id.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("The name of the room id #455 is %s.", getRoomName(455))<br />
</syntaxhighlight><br />
<br />
==getRooms==<br />
;rooms = getRooms()<br />
<br />
:Returns the list of '''all''' rooms in the map in the whole map in roomid - room name format.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- simple, raw viewer for rooms in the world<br />
display(getRooms())<br />
<br />
-- iterate over all rooms in code<br />
for id,name in pairs(getRooms()) do<br />
print(id, name)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomsByPosition==<br />
;roomTable = getRoomsByPosition(areaID, x,y,z)<br />
<br />
:Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.<br />
<br />
{{note}} The returned table starts indexing from '''0''' and not the usual lua index of '''1''', which means that using '''#''' to count the size of the returned table will produce erroneous results - use [[Manual:Table_Functions#table.size|table.size()]] instead.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sample alias to determine a room nearby, given a relative direction from the current room<br />
<br />
local otherroom<br />
if matches[2] == "" then<br />
local w = matches[3]<br />
local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)<br />
local has = table.contains<br />
if has({"west", "left", "w", "l"}, w) then<br />
x = (x or ox) - 1; y = (y or oy); z = (z or oz)<br />
elseif has({"east", "right", "e", "r"}, w) then<br />
x = (x or ox) + 1; y = (y or oy); z = (z or oz)<br />
elseif has({"north", "top", "n", "t"}, w) then<br />
x = (x or ox); y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"south", "bottom", "s", "b"}, w) then<br />
x = (x or ox); y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"northwest", "topleft", "nw", "tl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"northeast", "topright", "ne", "tr"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"southeast", "bottomright", "se", "br"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"up", "u"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) + 1<br />
elseif has({"down", "d"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) - 1<br />
end<br />
<br />
local carea = getRoomArea(mmp.currentroom)<br />
if not carea then mmp.echo("Don't know what area are we in.") return end<br />
<br />
otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))<br />
<br />
if not otherroom then<br />
mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return<br />
else<br />
mmp.echo("The room "..w.." of us has an ID of "..otherroom)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomUserData==<br />
;getRoomUserData(roomID, key)<br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or "" if none is stored. Use [[#setRoomUserData|setRoomUserData()]] function for setting the user data.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserData(341, "visitcount"))<br />
</syntaxhighlight><br />
<br />
:;getRoomUserData(roomID, key, enableFullErrorReporting)<br />
<br />
::Returns the user data value (string) stored at a given room with a given key (string), or, if the boolean value ''enableFullErrorReporting'' is true, ''nil'' and an error message if the key is not present or the room does not exist; if ''enableFullErrorReporting'' is false an empty string is returned but then it is not possible to tell if that particular value is actually stored or not against the given key.<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<!-- I would like this block to be indented to match the Example header but the mark-up system seems to be broken and only includes the first line<br />
if the start of the code line begins: ":<lua>..."--><br />
<syntaxhighlight lang="lua">local vNum = 341<br />
result, errMsg = getRoomUserData(vNum, "visitcount", true)<br />
if result ~= nil then<br />
display(result)<br />
else<br />
echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")<br />
end</syntaxhighlight><br />
<br />
==getRoomUserDataKeys==<br />
;getRoomUserDataKeys(roomID)<br />
<br />
:Returns all the keys for user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserDataKeys(3441))<br />
--might result in:--<br />
{<br />
"description",<br />
"doorname_up",<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getRoomWeight==<br />
;getRoomWeight(roomID)<br />
<br />
:Returns the weight of a room. By default, all new rooms have a weight of 1.<br />
: See also: [[#setRoomWeight|setRoomWeight()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Original weight of room 541: "..getRoomWeight(541))<br />
setRoomWeight(541, 3)<br />
display("New weight of room 541: "..getRoomWeight(541))<br />
</syntaxhighlight><br />
<br />
==getSpecialExits==<br />
;exits = getSpecialExits(roomID[, listAllExits])<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the special exits of.<br />
* ''listAllExits:''<br />
: (Since ''TBA'') In the case where there is more than one special exit to the same room ID list all of them.<br />
<br />
:Returns a roomid table of sub-tables containing name/command and exit lock status, of the special exits in the room. If there are no special exits in the room, the table returned will be empty.<br />
:Before ''TBA'' (likely to be Mudlet version '''4.11.0'''), if more than one special exit goes to the ''same'' exit room id then one of those exits is returned at random. Since ''TBA'' this will be the best (i.e. lowest-weight) exit that is '''not''' locked; should none be unlocked then the lowest locked one will be listed. In case of a tie, one of the tying exits will be picked at random.<br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- There are three special exits from 1337 to the room 42:<br />
-- "climb down ladder" which is locked and has an exit weight of 10<br />
-- "step out window" which is unlocked and has an exit weight of 20<br />
-- "jump out window" which is unlocked and has an exit weight of 990<br />
getSpecialExits(1337)<br />
<br />
-- In 4.10.1 and before this could results in:<br />
table {<br />
42 = {"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"climb down ladder" = "1"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA this will return:<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA, with the second argument as true, this gives:<br />
getSpecialExits(1337, true)<br />
table {<br />
42 = {"step out window" = "0",<br />
"climb down ladder" = "1",<br />
"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
</syntaxhighlight><br />
<br />
==getSpecialExitsSwap==<br />
;getSpecialExitsSwap(roomID)<br />
<br />
:Very similar to [[#getSpecialExits|getSpecialExits()]] function, but returns the rooms in the command - roomid style.<br />
<br />
==gotoRoom==<br />
;gotoRoom (roomID)<br />
:Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".<br />
<br />
In case this isn't working, and you are coding your own mapping script, [[Manual:Mapper#Making_your_own_mapping_script|see here]] how to implement additional functionality necessary.<br />
<br />
==hasExitLock==<br />
;status = hasExitLock(roomID, direction)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
-- check if the east exit of room 1201 is locked<br />
display(hasExitLock(1201, 4))<br />
display(hasExitLock(1201, "e"))<br />
display(hasExitLock(1201, "east"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#lockExit|lockExit()]]<br />
<br />
==hasSpecialExitLock==<br />
;hasSpecialExitLock(from roomID, to roomID, moveCommand)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. ''moveCommand'' is the action to take to get through the gate.<br />
<br />
See also: [[#lockSpecialExit|lockSpecialExit()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command<br />
lockSpecialExit(17463, 7814, 'enter feather', true)<br />
<br />
-- see if it is locked: it will say 'true', it is<br />
display(hasSpecialExitLock(17463, 7814, 'enter feather'))<br />
</syntaxhighlight><br />
<br />
==highlightRoom==<br />
;highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)<br />
<br />
:Highlights a room with the given color, which will override its environment color. If you use two different colors, then there'll be a shading from the center going outwards that changes into the other color. <br />
<br />
;Parameters<br />
* ''roomID''<br />
: ID of the room to be colored.<br />
* ''color1Red, color1Green, color1Blue''<br />
: RGB values of the first color.<br />
* ''color2Red, color2Green, color2Blue''<br />
: RGB values of the second color.<br />
* ''highlightRadius'' <br />
: The radius for the highlight circle - if you don't want rooms beside each other to overlap, use ''1'' as the radius. <br />
* ''color1Alpha'' and ''color2Alpha'' <br />
: Transparency values from 0 (completely transparent) to 255 (not transparent at all).<br />
<br />
: See also: [[#unHighlightRoom|unHighlightRoom()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- color room #351 red to blue<br />
local r,g,b = unpack(color_table.red)<br />
local br,bg,bb = unpack(color_table.blue)<br />
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)<br />
</syntaxhighlight><br />
<br />
==killMapInfo==<br />
;killMapInfo(label)<br />
<br />
Delete a map info contributor entirely - it will be not available anymore.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be removed was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==loadJsonMap==<br />
; loadJsonMap(pathFileName)<br />
<br />
; Parameters:<br />
<br />
* ''pathFileName'' a string that is an absolute path and file name to read the data from.<br />
<br />
Load the Mudlet map in text (JSON) format. It does take longer than loading usual map file (''.dat'' in binary) so it will show a progress dialog.<br />
<br />
: See also: [[#saveJsonMap|saveJsonMap()]]<br />
<br />
Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11.0}}<br />
<br />
==loadMap==<br />
;loadMap(file location)<br />
<br />
:Loads the map file from a given location. The map file must be in Mudlet's format - saved with [[#saveMap|saveMap()]] or, as of the Mudlet 3.0 may be a MMP XML map conforming to the structure used by I.R.E. for their downloadable maps for their MUD games. <br />
<br />
:Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.<br />
<br />
:Using no arguments will load the last saved map.<br />
<br />
<syntaxhighlight lang="lua"><br />
loadMap("/home/user/Desktop/Mudlet Map.dat")<br />
</syntaxhighlight><br />
<br />
{{Note}} A file name ending with <code>.xml</code> will indicate the XML format.<br />
<br />
==lockExit==<br />
;lockExit(roomID, direction, lockIfTrue)<br />
<br />
:Locks a given exit from a room. The destination may remain accessible through other paths, unlike [[#lockRoom|lockRoom]]. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
: See also: [[#hasExitLock|hasExitLock()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- lock the east exit of room 1201 so we never path through it<br />
lockExit(1201, 4, true)<br />
</syntaxhighlight><br />
<br />
==lockRoom==<br />
;lockRoom (roomID, lockIfTrue)<br />
<br />
:Locks a given room id from future speed walks (thus the mapper will never path through that room).<br />
: See also: [[#roomLocked | roomLocked()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockRoom(1, true) -- locks a room if from being walked through when speedwalking.<br />
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.<br />
</syntaxhighlight><br />
<br />
==lockSpecialExit==<br />
;lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)<br />
<br />
:Locks a given special exit, leading from one specific room to another that uses a certain command from future speed walks (thus the mapper will never path through that special exit).<br />
: See also: [[#hasSpecialExitLock | hasSpecialExitLock()]], [[#lockExit | lockExit()]], [[#lockRoom | lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2<br />
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit<br />
</syntaxhighlight><br />
<br />
==moveMapWidget==<br />
;moveMapWidget(Xpos, Ypos)<br />
:moves the map window to the given position.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
;Parameters<br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==openMapWidget==<br />
;openMapWidget([dockingArea | Xpos, Ypos, width, height])<br />
means either of these are fine:<br />
;openMapWidget()<br />
;openMapWidget(dockingArea)<br />
;openMapWidget(Xpos, Ypos, width, height)<br />
<br />
:opens a map window with given options.<br />
<br />
: See also: [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
{{note}} If no parameter is given the map window will be opened with the saved layout or at the right docking position (similar to clicking the icon)<br />
* ''dockingArea:''<br />
: If only one parameter is given this parameter will be a string that contains one of the possible docking areas the map window will be created in (f" floating "t" top "b" bottom "r" right and "l" left)<br />
{{note}} If 4 parameters are given the map window will be created in floating state <br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''width:''<br />
: The width map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height map window, in pixels. Passed as an integer number.<br />
<br />
==pauseSpeedwalk==<br />
;pauseSpeedwalk()<br />
<br />
:Pauses a speedwalk started using [[#speedwalk|speedwalk()]]<br />
<br />
: See also: [[#speedwalk|speedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = pauseSpeedwalk()<br />
if not ok then<br />
debugc(f"Error: unable to pause speedwalk because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
==registerMapInfo==<br />
;registerMapInfo(label, function)<br />
<br />
Adds an extra 'map info' to the mapper widget which can be used to display custom information.<br />
<br />
: See also: [[#killMapInfo|killMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
{{note}}<br />
You can register multiple map infos - just give them unique names and toggle whichever ones you need.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info will be registered and visible in select box under mapper. You can use it later to kill map info, enable it, disable it or overwrite using [[#registerMapInfo|registerMapInfo()]] again.<br />
* ''function:''<br />
: Callback function that will be responsible for returning information how to draw map info fragment.<br />
<br />
Callback function is called with following arguments:<br />
* ''roomId'' - current roomId or currently selected room (when multiple selection is made this is center room)<br />
* ''selectionSize'' - how many rooms are selected<br />
* ''areaId'' - roomId's areaId<br />
* ''displayedAreaId'' - areaId that is currently displayed<br />
<br />
Callback needs to return following:<br />
* ''text'' - text that will be displayed (when empty, nothing will be displayed, if you want to "reserve" line or lines use not empty value " " or add line breaks "\n")<br />
* ''isBold'' (optional) - true/false - determines whether text will be bold <br />
* ''isItalic'' (optional) - true/false - determines whether text will be italic<br />
* ''color r'' (optional) - color of text red component (0-255)<br />
* ''color g'' (optional) - color of text green component (0-255)<br />
* ''color b'' (optional) - color of text blue component (0-255)<br />
<br />
{{note}}<br />
Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.<br />
<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea) <br />
return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),<br />
true, true, 0, 255, 0<br />
end)<br />
enableMapInfo("My very own handler!")<br />
</syntaxhighlight><br />
<br />
Example will display something like that:<br />
<br />
[[File:Map-info-example.png]]<br />
<br />
Using function arguments is completely optional and you can determine whether and how to display map info completely externally.<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("Alert", function() <br />
if character.hp < 20 then<br />
return "Look out! Your HP is getting low", true, false, unpack(color_table.red) -- will display red, bolded warning whne character.hp is below 20<br />
else<br />
return "" -- will not return anything<br />
end<br />
end)<br />
enableMapInfo("Alert")<br />
</syntaxhighlight><br />
<br />
==resumeSpeedwalk==<br />
;resumeSpeedwalk()<br />
<br />
:Continues a speedwalk paused using [[#pauseSpeedwalk|pauseSpeedwalk()]]<br />
: See also: [[#speedwalk|speedwalk()]], [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = resumeSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")<br />
return<br />
end<br />
cecho("\n<green>Successfully resumed speedwalk!\n")<br />
</syntaxhighlight><br />
<br />
==removeCustomLine==<br />
;removeCustomLine(roomID, direction) <br />
<br />
:Removes the custom exit line that's associated with a specific exit of a room.<br />
:See also: [[#addCustomLine|addCustomLine()]], [[#getCustomLines|getCustomLines()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- remove custom exit line that starts in room 315 going north<br />
removeCustomLine(315, "n")<br />
</syntaxhighlight><br />
<br />
==removeMapEvent==<br />
;removeMapEvent(event name)<br />
<br />
:Removes the given menu entry from a mappers right-click menu. You can add custom ones with [[#addMapEvent | addMapEvent()]].<br />
: See also: [[#addMapEvent | addMapEvent()]], [[#getMapEvents | getMapEvents()]], [[#removeMapMenu | removeMapMenu()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- add one to the general menu<br />
removeMapEvent("room a") -- removes the said menu<br />
</syntaxhighlight><br />
<br />
==removeMapMenu==<br />
;removeMapMenu(menu name)<br />
<br />
:Removes the given submenu from a mappers right-click menu. You can add custom ones with [[#addMapMenu | addMapMenu()]].<br />
: See also: [[#addMapMenu | addMapMenu()]], [[#getMapMenus | getMapMenus()]], [[#removeMapEvent | removeMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Test") -- add submenu to the general menu<br />
removeMapMenu("Test") -- removes that same menu again<br />
</syntaxhighlight><br />
<br />
==removeSpecialExit==<br />
;removeSpecialExit(roomID, command) <br />
<br />
:Removes the special exit which is accessed by ''command'' from the room with the given ''roomID''.<br />
:See also: [[#addSpecialExit|addSpecialExit()]], [[#clearSpecialExits|clearSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2<br />
removeSpecialExit(1, "pull rope") -- removes the exit again<br />
</syntaxhighlight><br />
<br />
==resetRoomArea==<br />
;resetRoomArea (roomID)<br />
<br />
: Unassigns the room from its given area. While not assigned, its area ID will be -1. Note that since Mudlet 3.0 the "default area" which has the id of -1 may be selectable in the area selection widget on the mapper - although there is also an option to conceal this in the settings.<br />
<br />
: See also: [[#setRoomArea | setRoomArea()]], [[#getRoomArea | getRoomArea()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetRoomArea(3143)<br />
</syntaxhighlight><br />
<br />
==resizeMapWidget==<br />
;resizeMapWidget(width, height)<br />
:resizes a map window with given width, height.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
* ''width:''<br />
: The width of the map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the map window, in pixels. Passed as an integer number.<br />
<br />
==roomExists==<br />
;roomExists(roomID)<br />
<br />
:Returns a boolean true/false depending if the room with that ID exists (is created) or not.<br />
<br />
==roomLocked==<br />
;locked = roomLocked(roomID)<br />
<br />
:Returns true or false whenever a given room is locked.<br />
: See also: [[#lockRoom|lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))<br />
</syntaxhighlight><br />
<br />
==saveJsonMap==<br />
; saveJsonMap([pathFileName])<br />
Saves all the data that is normally held in the Mudlet map (''.dat'' as a binary format) in text (JSON) format. It does take longer to do this, so a progress dialog will be shown indicating the status. <br />
<br />
: See also: [[#loadJsonMap|loadJsonMap()]]<br />
{{MudletVersion|4.11.0}}<br />
<br />
; Parameters:<br />
* ''pathFileName'' (optional in Mudlet 4.12+): a string that is an absolute path and file name to save the data into.<br />
<br />
; Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
==saveMap==<br />
;saveMap([location], [version])<br />
<br />
:Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work. You can also save the map in the Mapper settings tab.<br />
<br />
;Parameters<br />
* ''location''<br />
: (optional) save the map to the given location if provided, or the default one otherwise.<br />
* ''version''<br />
: (optional) map version as a number to use when saving (Mudlet 3.17+)<br />
<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")<br />
if not savedok then<br />
echo("Couldn't save :(\n")<br />
else<br />
echo("Saved fine!\n")<br />
end<br />
<br />
-- save with a particular map version<br />
saveMap(20)<br />
</syntaxhighlight><br />
<br />
==searchAreaUserData==<br />
;searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])<br />
:Searches Areas' User Data in a manner exactly the same as [[#searchRoomUserData|searchRoomUserData()]] does in all Rooms' User Data, refer to that command for the specific details except to replace references to rooms and room ID numbers there with areas and areas ID numbers.<br />
<br />
==searchRoom== <br />
;searchRoom (room number | room name[, case-sensitive [, exact-match]])<br />
:Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of ''roomid = roomname'', the optional second and third boolean parameters have been available since Mudlet 3.0;<br />
<br />
::If no rooms are found, then an empty table is returned.<br />
<br />
:If you pass it a '''number''' instead of a '''string''' as just one argument, it'll act like [[#getRoomName|getRoomName()]] and return the room name.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- show the behavior when given a room number:<br />
display(searchRoom(3088))<br />
"The North Road South of Taren Ferry"<br />
<br />
-- show the behavior when given a string:<br />
-- shows all rooms containing the text in any case:<br />
display(searchRoom("North road"))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road",<br />
[3146] = "Bend in the North Road",<br />
[3088] = "The North Road South of Taren Ferry",<br />
[6229] = "Grassy Field By North Road"<br />
}<br />
-- or:<br />
-- display(searchRoom("North road",false))<br />
-- display(searchRoom("North road",false,false))<br />
-- would both also produce those results.<br />
<br />
-- shows all rooms containing the text in ONLY the letter-case provided:<br />
display(searchRoom("North road",true,false))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3117] = "North road",<br />
}<br />
<br />
-- shows all rooms containing ONLY that text in either letter-case:<br />
lua searchRoom("North road",false,true)<br />
{<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road"<br />
}<br />
<br />
-- shows all rooms containing only and exactly the given text:<br />
lua searchRoom("North road",true,true)<br />
{<br />
[3115] = "North road",<br />
[3117] = "North road"<br />
}<br />
</syntaxhighlight><br />
{{note}} Technically, with both options (case-sensitive and exact-match) set to true, one could just return a list of numbers as we know precisely what the string will be, but it was kept the same for maximum flexibility in user scripts.<br />
<br />
==searchRoomUserData== <br />
;searchRoomUserData([key, [value]])<br />
:A command with three variants that search though all the rooms in sequence (so '''not as fast as a user built/maintained ''index'' system''') and find/reports on the room user data stored:<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;searchRoomUserData(key, value)<br />
<br />
:Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key". <br />
<br />
;searchRoomUserData(key)<br />
<br />
:Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key". <br />
<br />
;searchRoomUserData()<br />
<br />
:Reports a (sorted) list of the unique keys from all rooms with user data with any (case sensitive) "key", available since Mudlet 3.0. It is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if I had stored the details of "named doors" as part of the room user data --<br />
display(searchRoomUserData("doorname_up"))<br />
<br />
--[[ could result in a list:<br />
{<br />
"Eastgate",<br />
"Northgate",<br />
"boulderdoor",<br />
"chamberdoor",<br />
"dirt",<br />
"floorboards",<br />
"floortrap",<br />
"grate",<br />
"irongrate",<br />
"rockwall",<br />
"tomb",<br />
"trap",<br />
"trapdoor"<br />
}]]<br />
<br />
-- then taking one of these keys --<br />
display(searchRoomUserData("doorname_up","trapdoor"))<br />
<br />
--[[ might result in a list:<br />
{<br />
3441,<br />
6113,<br />
6115,<br />
8890<br />
}<br />
]]</syntaxhighlight><br />
<br />
==setAreaName==<br />
;setAreaName(areaID or areaName, newName)<br />
<br />
:Names, or renames an existing area to the new name. The area must be created first with [[#addAreaName|addAreaName()]] and it must be unique.<br />
<br />
{{note}} parameter areaName is available since Mudlet 3.0.<br />
<br />
:See also: [[#deleteArea|deleteArea()]], [[#addAreaName|addAreaName()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setAreaName(2, "My city")<br />
<br />
-- available since Mudlet 3.0<br />
setAreaName("My old city name", "My new city name")<br />
</syntaxhighlight><br />
<br />
==setAreaUserData==<br />
;setAreaUserData(areaID, key (as a string), value (as a string))<br />
<br />
:Stores information about an area under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. Returns a lua ''true'' value on success. You can have as many keys as you'd like, however a blank key will not be accepted and will produce a lua ''nil'' and an error message instead.<br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#getAreaUserData|getAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store extra area details...<br />
setAreaUserData(34, "country", "Andor.")<br />
<br />
-- or a sound file to play in the background (with a script that checks a room's area when entered)...<br />
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))<br />
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)<br />
</syntaxhighlight><br />
<br />
==setCustomEnvColor==<br />
;setCustomEnvColor(environmentID, r,g,b,a)<br />
<br />
:Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.<br />
: See also: [[#getCustomEnvColorTable|getCustomEnvColorTable()]], [[#setRoomEnv|setRoomEnv()]]<br />
<br />
{{note}} Numbers 1-16 and 257-272 are reserved by Mudlet. 257-272 are the default colors the user can adjust in mapper settings, so feel free to use them if you'd like - but don't overwrite them with this function.<br />
<br />
[[File:Screenshot 20240305 115555.png|thumb|center|Default colour table for Mudlet mapper.]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200<br />
local r,g,b = unpack(color_table.blue)<br />
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue<br />
</syntaxhighlight><br />
<br />
==setDoor==<br />
;setDoor(roomID, exitCommand, doorStatus)<br />
<br />
:Creates or deletes a door in a room. Doors are purely visual - they don't affect pathfinding. You can use the information to adjust your speedwalking path based on the door information in a room, though.<br />
<br />
:Doors CAN be set on stub exits ''- so that map makers can note if there is an obvious door to somewhere even if they do not (yet) know where it goes, perhaps because they do not yet have the key to open it!''<br />
<br />
:Returns ''true'' if the change could be made, ''false'' if the input was valid but ineffective (door status was not changed), and ''nil'' with a message string on invalid input (value type errors).<br />
<br />
: See also: [[#getDoors|getDoors()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to create the door in.<br />
* ''exitCommand:''<br />
: The cardinal direction for the door is in - it can be one of the following: '''n''', '''e''', '''s''', '''w''', '''ne''', '''se''', '''sw''', '''ne'''. ''{Plans are afoot to add support for doors on the other normal exits: '''up''', '''down''', '''in''' and '''out''', and also on special exits - though more work will be needed for them to be shown in the mapper.}'' It is important to ONLY use these direction codes as others e.g. "UP" will be accepted - because a special exit could have ANY name/lua script - but it will not be associated with the particular normal exit - recent map auditing code about to go into the code base will REMOVE door and other room exit items for which the appropriate exit (or stub) itself is not present, so in this case, in the absence of a special exit called "UP" that example door will not persist and not show on the normal "up" exit when that is possible later on.<br />
<br />
* ''doorStatus:''<br />
: The door status as a number - '''0''' means no (or remove) door, '''1''' means open door (will draw a green square on exit), '''2''' means closed door (yellow square) and '''3''' means locked door (red square). <br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a door on the east exit of room 4234 that is currently open<br />
setDoor(4234, 'e', 1)<br />
<br />
-- remove a door from room 923 that points north<br />
setDoor(923, 'n', 0)<br />
</syntaxhighlight><br />
<br />
==setExit==<br />
;setExit(from roomID, to roomID, direction)<br />
<br />
:Creates a one-way exit from one room to another using a standard direction - which can be either one of ''n, ne, nw, e, w, s, se, sw, u, d, in, out'', the long version of a direction, or a number which represents a direction. If there was an exit stub in that direction already, then it will be automatically deleted for you.<br />
<br />
:Returns ''false'' if the exit creation didn't work.<br />
<br />
: See also: [[#addSpecialExit|addSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^exit (\d+) (\d+) (\w+)$<br />
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north<br />
<br />
if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then<br />
echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))<br />
else<br />
echo("Failed to set the exit.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
This function can also delete exits from a room if you use it like so:<br />
<br />
<syntaxhighlight lang="lua">setExit(from roomID, -1, direction)</syntaxhighlight><br />
<br />
- which will delete an outgoing exit in the specified direction from a room.<br />
<br />
==setExitStub==<br />
;setExitStub(roomID, direction, set/unset)<br />
<br />
Creates or removes an exit stub from a room in a given directions. You can use exit stubs later on to connect rooms that you're sure of are together. Exit stubs are also shown visually on the map, so the mapper can easily tell which rooms need finishing.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room to place an exit stub in, as a number.<br />
* ''direction:''<br />
: The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.<br />
* ''set/unset:''<br />
: A boolean to create or delete the exit stub.<br />
<br />
: See also: [[#getExitStubs|getExitStubs()]], [[#connectExitStub|connectExitStub()]]<br />
<br />
;Example<br />
Create an exit stub to the south from room 8:<br />
<syntaxhighlight lang="lua"><br />
setExitStub(8, "s", true)<br />
</syntaxhighlight><br />
<br />
How to delete all exit stubs in a room:<br />
<syntaxhighlight lang="lua"><br />
for i,v in pairs(getExitStubs(roomID)) do<br />
setExitStub(roomID, v,false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setExitWeight==<br />
;setExitWeight(roomID, exitCommand, weight)<br />
<br />
:Gives an exit a weight, which makes it less likely to be chosen for pathfinding. All exits have a weight of 0 by default, which you can increase. Exit weights are set one-way on an exit - if you'd like the weight to be applied both ways, set it from the reverse room and direction as well.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set the weight in.<br />
* ''exitCommand:''<br />
: The direction for the exit is in - it can be one of the following: '''n''', '''ne''', '''e''', '''se''', '''s''', '''sw''', '''w''', '''nw''', '''up''', '''down''', '''in''', '''out''', or, if it's a special exit, the special exit command - note that the strings for normal exits are case-sensitive and must currently be exactly as given here.<br />
* ''weight:''<br />
: Exit weight - by default, all exits have a weight of 0 meaning that the weight of the ''destination room'' is use when the route finding code is considering whether to use that exit; setting a value for an exit can increase or decrease the chance of that exit/destination room being used for a route by the route-finding code. For example, if the destination room has very high weight compared to it's neighbors but the exit has a low value then that exit and thus the room is more likely to be used than if the exit was not weighted.<br />
<br />
: See also: [[#getExitWeights|getExitWeights()]]<br />
<br />
==setGridMode==<br />
;setGridMode(areaID, true/false)<br />
<br />
:Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode; for the 2D map the custom exit lines will also not be shown if this mode is enabled. <br />
:Returns true if the area exists, otherwise false.<br />
:[[File:Mapper-regular-mode.png|none|thumb|640x640px|regular mode]][[File:Mapper-grid-mode.png|none|thumb|631x631px|grid mode]]<br />
<br />
: See also: [[#getGridMode|getGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
</syntaxhighlight><br />
<br />
==setMapUserData==<br />
;setMapUserData(key (as a string), value (as a string))<br />
<br />
:Stores information about the map under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearMapUserData|clearMapUserData()]], [[#clearMapUserDataItem|clearMapUserDataItem()]], [[#getAllMapUserData|getAllMapUserData()]], [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- store general meta information about the map...<br />
setMapUserData("game_name", "Achaea Mudlet map")<br />
<br />
-- or who the author was<br />
setMapUserData("author", "Bob")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))<br />
display("Available game info in the map: ")<br />
display(yajl.to_value(getMapUserData("some table")))<br />
</syntaxhighlight><br />
<br />
==setMapZoom==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''4.17.0''''' to allow the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet permanently remembering (it is saved within the map file) the zoom level last used for each area and with the addition of the ''getMapZoom()'' function.<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapZoom|getMapZoom()]].<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
:(Optional and only since '''Mudlet ''4.17.0''''') Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''4.17.0''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is 3.0 and the initial value - and what prior Mudlet versions started each session with - is 20.0.<br />
<br />
==setRoomArea==<br />
;setRoomArea(roomID, newAreaID or newAreaName)<br />
<br />
:Assigns the given room to a new or different area. If the area is displayed in the mapper this will have the room be visually moved into the area as well.<br />
<br />
: See also: [[#resetRoomArea|resetRoomArea()]]<br />
<br />
==setRoomChar==<br />
;setRoomChar(roomID, character)<br />
<br />
:Originally designed for an area in grid mode, takes a single ASCII character and draws it on the rectangular background of the room in the 2D map. In versions prior to Mudlet 3.8, the symbol can be cleared by using "_" as the character. In Mudlet version 3.8 and higher, the symbol may be cleared with either a space <code>" "</code> or an empty string <code>""</code>.<br />
<br />
;Game-related symbols for your map<br />
* [https://github.com/toddfast/game-icons-net-font toddfast's font] - 3000+ scalable vector RPG icons from [https://game-icons.net game-icons.net], as well as a script to download the latest icons and generate a new font.<br />
* Pixel Kitchen's [https://www.fontspace.com/donjonikons-font-f30607 Donjonikon Font] - 10x10 fantasy and RPG-related icons.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomChar(431, "#")<br />
<br />
setRoomChar(123, "$")<br />
<br />
-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings<br />
setRoomChar(666, "👿")<br />
</syntaxhighlight><br />
<br />
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><br />
<div style="font-weight:bold;line-height:1.6;">Historical version information</div><br />
<div class="mw-collapsible-content"><br />
:Since Mudlet version 3.8 this feature has been extended:<br />
:* This function will now take a short string of any printable characters as a room ''symbol'', and they will be shrunk to fit them all in horizontally but if they become too small that ''symbol'' may not be shown if the zoom is such that the room symbol is too small to be legible.<br />
:* As "_" is now a valid character an existing symbol may be erased with either a space " " or an empty string "" although neither may be effective in some previous versions of Mudlet.<br />
:* Should the rooms be set to be drawn as circles this is now accommodated and the symbol will be resized to fit the reduce drawing area this will cause.<br />
:* The range of characters that are available are now dependent on the '''fonts''' present in the system and a setting on the "Mapper" tab in the preferences that control whether a specific font is to be used for all symbols (which is best if a font is included as part of a game server package, but has the issue that it may not be displayable if the user does not have that font or chooses a different one) or any font in the user's system may be used (which is the default, but may not display the ''glyph'' {the particular representation of a ''grapheme'' in a particular font} that the original map creator expected). Should it not be possible to display the wanted symbol in the map because one or more of the required glyphs are not available in either the specified or any font depending on the setting then the ''replacement character'' (Unicode ''code-point'' U+FFFD '�') will be shown instead. To allow such missing symbols to be handled the "Mapper" tab on the preferences dialogue has an option to display:<br />
::* an indicator to show whether the symbol can be made just from the selected font (green tick), from the fonts available in the system (yellow warning triangle) or not at all (red cross)<br />
::* all the symbols used on the map and how they will be displayed both only using the selected font and all fonts<br />
::* the sequence of code-points used to create the symbol which will be useful when used in conjunction with character selection utilities such as ''charmap.exe'' on Windows and ''gucharmap'' on unix-like system<br />
::* a count of the rooms using the particular symbol<br />
::* a list, limited in entries of the first rooms using that symbol<br />
:* The font that is chosen to be used as the primary (or only) one for the room symbols is stored in the Mudlet map data so that setting will be included if a binary map is shared to other Mudlet users or profiles on the same system.<br />
</div></div></div><br />
<br />
<br />
: See also: [[#getRoomChar|getRoomChar()]]<br />
<br />
==setRoomCharColor==<br />
;setRoomCharColor(roomId, r, g, b)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set char color to.<br />
* ''r:''<br />
: Red component of room char color (0-255)<br />
* ''g:''<br />
: Green component of room char color (0-255)<br />
* ''b:''<br />
: Blue component of room char color (0-255)<br />
<br />
Sets color for room symbol.<br />
<br />
<syntaxhighlight lang="lua"><br />
setRoomCharColor(2402, 255, 0, 0)<br />
setRoomCharColor(2403, 0, 255, 0)<br />
setRoomCharColor(2404, 0, 0, 255)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
: See also: [[#unsetRoomCharColor|unsetRoomCharColor()]]<br />
<br />
==setRoomCoordinates==<br />
;setRoomCoordinates(roomID, x, y, z)<br />
<br />
:Sets the given room ID to be at the following coordinates visually on the map, where ''z'' is the up/down level. These coordinates are define the location of the room within a particular area (so not globally on the overall map).<br />
<br />
{{note}} 0,0,0 is the center of the map.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$<br />
-- this sets the current room to the supplied coordinates<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
:You can make them relative asa well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^src (\w+)$<br />
<br />
local x,y,z = getRoomCoordinates(previousRoomID)<br />
local dir = matches[2]<br />
<br />
if dir == "n" then<br />
y = y+1<br />
elseif dir == "ne" then<br />
y = y+1<br />
x = x+1<br />
elseif dir == "e" then<br />
x = x+1<br />
elseif dir == "se" then<br />
y = y-1<br />
x = x+1<br />
elseif dir == "s" then<br />
y = y-1<br />
elseif dir == "sw" then<br />
y = y-1<br />
x = x-1<br />
elseif dir == "w" then<br />
x = x-1<br />
elseif dir == "nw" then<br />
y = y+1<br />
x = x-1<br />
elseif dir == "u" or dir == "up" then<br />
z = z+1<br />
elseif dir == "down" then<br />
z = z-1<br />
end<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
==setRoomEnv==<br />
;setRoomEnv(roomID, newEnvID)<br />
<br />
:Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34<br />
</syntaxhighlight><br />
<br />
==setRoomIDbyHash==<br />
;setRoomIDbyHash(roomID, hash)<br />
<br />
:Sets the hash to be associated with the given roomID. See also [[#getRoomIDbyHash|getRoomIDbyHash()]].<br />
<br />
:If the room was associated with a different hash, or vice versa, that association will be superseded.<br />
<br />
==setRoomName==<br />
;setRoomName(roomID, newName)<br />
<br />
:Renames an existing room to a new name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomName(534, "That evil room I shouldn't visit again.")<br />
lockRoom(534, true) -- and lock it just to be safe<br />
</syntaxhighlight><br />
<br />
==setRoomUserData==<br />
;setRoomUserData(roomID, key (as a string), value (as a string))<br />
<br />
:Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store room descriptions...<br />
setRoomUserData(341, "description", "This is a plain-looking room.")<br />
<br />
-- or whenever it's outdoors or not...<br />
setRoomUserData(341, "outdoors", "true")<br />
<br />
-- how how many times we visited that room<br />
local visited = getRoomUserData(341, "visitcount")<br />
visited = (tonumber(visited) or 0) + 1<br />
setRoomUserData(341, "visitcount", tostring(visited))<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))<br />
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)<br />
</syntaxhighlight><br />
<br />
==setRoomWeight==<br />
;setRoomWeight(roomID, weight)<br />
<br />
:Sets a weight to the given roomID. By default, all rooms have a weight of 1 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.<br />
<br />
{{note}} The minimum allowed room weight is 1. <br />
<br />
:To completely avoid a room, make use of [[#lockRoom|lockRoom()]].<br />
<br />
: See also: [[#getRoomWeight|getRoomWeight()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it<br />
</syntaxhighlight><br />
<br />
<br />
==speedwalk==<br />
;speedwalk(dirString, backwards, delay, show)<br />
<br />
:A speedwalking function will work on cardinal+ordinal directions (n, ne, e, etc.) as well as u (for up), d (for down), in and out. It can be called to execute all directions directly after each other, without delay, or with a custom delay, depending on how fast your game allows you to walk. It can also be called with a switch to make the function reverse the whole path and lead you backwards.<br />
<br />
:Call the function by doing: <code>speedwalk("YourDirectionsString", true/false, delaytime, true/false)</code><br />
<br />
:The delaytime parameter will set a delay between each move (set it to 0.5 if you want the script to move every half second, for instance). It is optional: If you don't indicate it, the script will send all direction commands right after each other. (If you want to indicate a delay, you -have- to explicitly indicate true or false for the reverse flag.)<br />
<br />
:The show parameter will determine if the commands sent by this function are shown or hidden. It is optional: If you don't give a value, the script will show all commands sent. (If you want to use this option, you -have- to explicitly indicate true or false for the reverse flag, as well as either some number for the delay or nil if you do not want a delay.)<br />
<br />
:The "YourDirectionsString" contains your list of directions and steps (e.g.: "2n, 3w, u, 5ne"). Numbers indicate the number of steps you want it to walk in the direction specified after it. The directions must be separated by anything other than a letter that can appear in a direction itself. (I.e. you can separate with a comma, spaces, the letter x, etc. and any such combinations, but you cannot separate by the letter "e", or write two directions right next to each other with nothing in-between, such as "wn". If you write a number before every direction, you don't need any further separator. E.g. it's perfectly acceptable to write "3w1ne2e".) The function is not case-sensitive.<br />
<br />
:If your game only has cardinal directions (n,e,s,w and possibly u,d) and you wish to be able to write directions right next to each other like "enu2s3wdu", you'll have to change the pattern slightly. Likewise, if your game has any other directions than n, ne, e, se, s, sw, w, nw, u, d, in, out, the function must be adapted to that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
speedwalk("16d1se1u")<br />
-- Will walk 16 times down, once southeast, once up. All in immediate succession.<br />
<br />
speedwalk("2ne,3e,2n,e")<br />
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.<br />
<br />
speedwalk("IN N 3W 2U W", false, 0.5)<br />
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.<br />
<br />
speedwalk("5sw - 3s - 2n - w", true)<br />
-- Will walk backwards: east, twice south, thrice north, five times northeast. All in immediate succession.<br />
<br />
speedwalk("3w, 2ne, w, u", true, 1.25)<br />
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.<br />
</syntaxhighlight><br />
<br />
{{note}} The probably most logical usage of this would be to put it in an alias. For example, have the pattern ''^/(.+)$'' execute: <code>speedwalk(matches[2], false, 0.7)</code><br />
And have ''^//(.+)$'' execute: <code>speedwalk(matches[2], true, 0.7)</code><br />
Or make aliases like: ''^banktohome$'' to execute <syntaxhighlight lang="lua" inline>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight><br />
<br />
{{note}} The show parameter for this function is available in Mudlet 3.12+<br />
<br />
==stopSpeedwalk==<br />
;stopSpeedwalk()<br />
<br />
:Stops a speedwalk started using [[#speedwalk|speedwalk()]]<br />
: See also: [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]], [[#speedwalk|speedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = stopSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> {err}")<br />
return<br />
end<br />
cecho(f"\n<green>Success:<reset> speedwalk stopped")<br />
</syntaxhighlight><br />
<br />
==unHighlightRoom==<br />
;unHighlightRoom(roomID)<br />
<br />
:Unhighlights a room if it was previously highlighted and restores the rooms original environment color.<br />
: See also: [[#highlightRoom|highlightRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
unHighlightRoom(4534)<br />
</syntaxhighlight><br />
<br />
==unsetRoomCharColor==<br />
;unsetRoomCharColor(roomId)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to unset char color to.<br />
<br />
Removes char color setting from room, back to automatic determination based on room background lightness.<br />
<br />
<syntaxhighlight lang="lua"><br />
unsetRoomCharColor(2031)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==updateMap==<br />
;updateMap()<br />
<br />
:Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.<br />
<br />
: See also: [[#centerview|centerview()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete a some room<br />
deleteRoom(500)<br />
-- now make the map show that it's gone<br />
updateMap()<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=21514Compiling Mudlet2024-03-19T18:30:22Z<p>Vadi: /* Compiling on Debian 'Sid' */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|400px|none]]<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
* Open powershell in the newly cloned folder by typing in <code>powershell</code> in the address bar:<br />
<br />
[[File:Open powershell in a folder.png|none|thumb|418x418px]]<br />
<br />
* Run <code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted</code> to enable the setup script to run and press <code>A</code>.<br />
* Run <code>./setup-windows-sdk.ps1</code><br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
Here's a rundown on checking you can use luarocks. Here we will use the bit32 module as an example.<br />
<br />
<br />
1. Install via luarocks<br />
<br />
> luarocks install bit32<br />
<br />
2. Check where luarocks installs the modules. Note the modules section.<br />
<br />
<nowiki><br />
> luarocks show bit32<br />
<br />
bit32 5.3.5.1-1 - Lua 5.2 bit manipulation library<br />
<br />
bit32 is the native Lua 5.2 bit manipulation library, in the version from Lua 5.3; it is compatible with Lua 5.1, 5.2, 5.3 and 5.4.<br />
<br />
License: MIT<br />
Homepage: http://www.lua.org/manual/5.2/manual.html#6.7<br />
Installed in: /usr/local<br />
<br />
Modules:<br />
bit32 (/usr/local/lib/lua/5.1/bit32.so)<br />
<br />
Depends on:<br />
lua >= 5.1, < 5.5 (using 5.1-1)<br />
</nowiki><br />
<br />
3. Recompile mudlet. You may need to adjust lua path and cpath information for your environment. You can use the following commands to help find this information.<br />
<br />
<nowiki><br />
> luarocks --lua-version 5.1 path --no-bin<br />
export LUA_PATH='./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua'<br />
export LUA_CPATH='./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so<br />
</nowiki><br />
<br />
Or from within mudlet itself you can issue these commands to double check the correct paths are being used.<br />
<br />
<nowiki><br />
> lua print(package.path)<br />
/home/username/.config/mudlet/profiles/localhost/?.lua;/home/zooka/.config/mudlet/profiles/localhost/?/init.lua;./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua <br />
<br />
> lua print(package.cpath)<br />
/home/username/.config/mudlet/profiles/localhost/?.so;/home/username/Workspace/mudlet-dev/Mudlet/build/lib/?.so;./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so<br />
</nowiki><br />
<br />
4. Recompile and run a test script using the [https://www.lua.org/pil/8.1.html require command] to load in the necessary library.<br />
<br />
<nowiki><br />
bit32 = require("bit32")<br />
<br />
function bit32_test()<br />
bit32.band(0,1)<br />
end<br />
</nowiki><br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=21513Compiling Mudlet2024-03-19T18:29:57Z<p>Vadi: /* Compiling on Debian 11 'Bullseye' */ remove instructions for old debian</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|400px|none]]<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
* Open powershell in the newly cloned folder by typing in <code>powershell</code> in the address bar:<br />
<br />
[[File:Open powershell in a folder.png|none|thumb|418x418px]]<br />
<br />
* Run <code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted</code> to enable the setup script to run and press <code>A</code>.<br />
* Run <code>./setup-windows-sdk.ps1</code><br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
Here's a rundown on checking you can use luarocks. Here we will use the bit32 module as an example.<br />
<br />
<br />
1. Install via luarocks<br />
<br />
> luarocks install bit32<br />
<br />
2. Check where luarocks installs the modules. Note the modules section.<br />
<br />
<nowiki><br />
> luarocks show bit32<br />
<br />
bit32 5.3.5.1-1 - Lua 5.2 bit manipulation library<br />
<br />
bit32 is the native Lua 5.2 bit manipulation library, in the version from Lua 5.3; it is compatible with Lua 5.1, 5.2, 5.3 and 5.4.<br />
<br />
License: MIT<br />
Homepage: http://www.lua.org/manual/5.2/manual.html#6.7<br />
Installed in: /usr/local<br />
<br />
Modules:<br />
bit32 (/usr/local/lib/lua/5.1/bit32.so)<br />
<br />
Depends on:<br />
lua >= 5.1, < 5.5 (using 5.1-1)<br />
</nowiki><br />
<br />
3. Recompile mudlet. You may need to adjust lua path and cpath information for your environment. You can use the following commands to help find this information.<br />
<br />
<nowiki><br />
> luarocks --lua-version 5.1 path --no-bin<br />
export LUA_PATH='./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua'<br />
export LUA_CPATH='./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so<br />
</nowiki><br />
<br />
Or from within mudlet itself you can issue these commands to double check the correct paths are being used.<br />
<br />
<nowiki><br />
> lua print(package.path)<br />
/home/username/.config/mudlet/profiles/localhost/?.lua;/home/zooka/.config/mudlet/profiles/localhost/?/init.lua;./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua <br />
<br />
> lua print(package.cpath)<br />
/home/username/.config/mudlet/profiles/localhost/?.so;/home/username/Workspace/mudlet-dev/Mudlet/build/lib/?.so;./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so<br />
</nowiki><br />
<br />
4. Recompile and run a test script using the [https://www.lua.org/pil/8.1.html require command] to load in the necessary library.<br />
<br />
<nowiki><br />
bit32 = require("bit32")<br />
<br />
function bit32_test()<br />
bit32.band(0,1)<br />
end<br />
</nowiki><br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21509Standards:GMCP Authentication2024-03-13T07:19:20Z<p>Vadi: /* Char.Login.Credentials */</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Char.Login</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Char.Login.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, or as soon as telnet negotiation completes, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Char.Login.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Char.Login.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Char.Login.Result ===== <br />
Sent in response to <code>Char.Login.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Char.Login.Credentials ===== <br />
After receiving <code>Char.Login.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name can be included after a colon (:), for example <code>myaccount:mycharacter</code>.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
In case the client does not know both the character name and password, it may notify the server of this by sending an empty response. This can be used a response to any authentication method:<br />
<br />
<code>Char.Login.Credentials {}</code><br />
<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Char.Login 1&quot;, ...]</code><br />
# Server responds with: <code>Char.Login.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Char.Login.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21508Standards:GMCP Authentication2024-03-12T06:31:21Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Char.Login</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Char.Login.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, or as soon as telnet negotiation completes, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Char.Login.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Char.Login.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Char.Login.Result ===== <br />
Sent in response to <code>Char.Login.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Char.Login.Credentials ===== <br />
After receiving <code>Char.Login.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name can be included after a colon (:), for example <code>myaccount:mycharacter</code>.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
In case the client does not know both the character name and password, it may notify the server of this by sending an empty array. This can be used a response to any authentication method:<br />
<br />
<code>Char.Login.Credentials {}</code><br />
<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Char.Login 1&quot;, ...]</code><br />
# Server responds with: <code>Char.Login.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Char.Login.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=File:GMCP_authentication_flow.png&diff=21507File:GMCP authentication flow.png2024-03-12T06:31:07Z<p>Vadi: Vadi uploaded a new version of File:GMCP authentication flow.png</p>
<hr />
<div>Sequence diagram describing the GMCP authentication flow</div>Vadihttps://wiki.mudlet.org/index.php?title=File:GMCP_authentication_flow.png&diff=21492File:GMCP authentication flow.png2024-02-28T15:18:48Z<p>Vadi: Vadi uploaded a new version of File:GMCP authentication flow.png</p>
<hr />
<div>Sequence diagram describing the GMCP authentication flow</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21491Standards:GMCP Authentication2024-02-28T15:18:25Z<p>Vadi: Rename to Char.Login</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Char.Login</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Char.Login.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, or as soon as telnet negotiation completes, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Char.Login.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Char.Login.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Char.Login.Result ===== <br />
Sent in response to <code>Char.Login.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Char.Login.Credentials ===== <br />
After receiving <code>Char.Login.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name can be included after a colon (:), for example <code>myaccount:mycharacter</code>.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Char.Login 1&quot;, ...]</code><br />
# Server responds with: <code>Char.Login.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Char.Login.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21490Standards:GMCP Authentication2024-02-28T15:03:28Z<p>Vadi: /* Client.Authenticate.Default */ add an optimisation for sending supports quicker</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, or as soon as telnet negotiation completes, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Client.Authenticate.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
After receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name can be included after a colon (:), for example <code>myaccount:mycharacter</code>.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=21487Compiling Mudlet2024-02-21T17:15:52Z<p>Vadi: /* Compiling on Windows */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
* Open powershell in the newly cloned folder by typing in <code>powershell</code> in the address bar:<br />
<br />
[[File:Open powershell in a folder.png|none|thumb|418x418px]]<br />
<br />
* Run <code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted</code> to enable the setup script to run and press <code>A</code>.<br />
* Run <code>./setup-windows-sdk.ps1</code><br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=21486Compiling Mudlet2024-02-21T17:15:08Z<p>Vadi: /* Compiling on Windows */ update run instructions</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
* Open powershell in the newly cloned folder by typing in <code>powershell</code> in the address bar:<br />
<br />
[[File:Open powershell in a folder.png|none|thumb|418x418px]]<br />
<br />
* Run <code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted</code> to enable the setup script.<br />
* Run <code>./setup-windows-sdk.ps1</code><br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=File:Open_powershell_in_a_folder.png&diff=21485File:Open powershell in a folder.png2024-02-21T17:08:51Z<p>Vadi: </p>
<hr />
<div>Screenshot of how to open powershell in a folder</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21484Standards:GMCP Authentication2024-02-19T08:52:19Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Client.Authenticate.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
After receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name can be included after a colon (:), for example <code>myaccount:mycharacter</code>.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21483Standards:GMCP Authentication2024-02-17T13:54:46Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Client.Authenticate.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
After receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name would be handled in plain text outside of this spec.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;account&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authentication flow.png|alt=|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=File:GMCP_authentication_flow.png&diff=21482File:GMCP authentication flow.png2024-02-17T13:54:38Z<p>Vadi: </p>
<hr />
<div>Sequence diagram describing the GMCP authentication flow</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21481Standards:GMCP Authentication2024-02-17T13:11:52Z<p>Vadi: Externalise OAuth and support accounts</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code> (array of strings, required): indicates the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: traditional username/password login.<br />
** <code>oauth</code>: OAuth-based login.<br />
*<code>location</code> (string, required if <code>type</code> is <code>oauth</code>): openid-configuration location. See https://openid.net/specs/openid-connect-discovery-1_0.html<br />
<br />
Since multiple flows can be supported by a server, the <code>type</code> array shall be ordered in the descending order of preference by the server. For example, if the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both OAuth and credentials and prefers OAuth:<br />
<br />
Client.Authenticate.Default {"type": ["oauth", "password-credentials"], "location": "<nowiki>https://example.com/.well-known/openid-configuration</nowiki>" }<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean, required) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string, required if <code>success</code> is false) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
After receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, the client sends the character name and password for traditional login.<br />
<br />
* <code>account</code> (string, required): character name or the player account name. For games that implement both player and character names, the character name would be handled in plain text outside of this spec.<br />
* <code>password</code> (string, required): character password. Servers are encouraged to implement [[Manual:Supported Protocols#Secure connection .28TLS.29|TLS over telnet]] to allow secure transmission of passwords.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
<br />
<br />
'''OAuth Flows'''<br />
<br />
Specific details for the OAuth flow will be detailed once it is worked out with the community.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21480Standards:GMCP Authentication2024-02-17T08:10:02Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: Traditional username/password login.<br />
** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Authenticate.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
Sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21479Standards:GMCP Authentication2024-02-17T08:04:28Z<p>Vadi: /* Client.Authenticate.Default */</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: Traditional username/password login.<br />
** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Authenticate.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Authenticate.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
Sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
<br />
===== Client.Authenticate.OAuth===== <br />
Sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21478Standards:GMCP Authentication2024-02-17T08:04:08Z<p>Vadi: /* Client.Authenticate.Default */</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: Traditional username/password login.<br />
** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.<code>Authenticate</code>.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.<code>Authenticate</code>.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
Sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
<br />
===== Client.Authenticate.OAuth===== <br />
Sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21477Standards:GMCP Authentication2024-02-17T07:34:36Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: Traditional username/password login.<br />
** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Auth.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Auth.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
Sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
<br />
===== Client.Authenticate.OAuth===== <br />
Sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
<br />
<br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21476Standards:GMCP Authentication2024-02-17T07:32:45Z<p>Vadi: Formatting changes for consistency with GMCP Discord and easier linking</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
==== Server-side ====<br />
<br />
===== Client.Authenticate.Default=====<br />
<br />
Sent in response to <code>Client.Supports.Set</code>, it informs the client of the supported authentication methods:<br />
*<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
**<code>password-credentials</code>: Traditional username/password login.<br />
** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Auth.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Auth.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
===== Client.Authenticate.Result ===== <br />
Sent in response to <code>Client.Authenticate.Credentials</code>, it informs the client of the success or failure of the credentials-based login. <br />
* <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
* <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
==== Client-side ====<br />
<br />
===== Client.Authenticate.Credentials ===== <br />
Sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
<br />
===== Client.Authenticate.OAuth===== <br />
Sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21475Standards:GMCP Authentication2024-02-17T07:26:25Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
'''Server-side:'''<br />
<br />
* <code>Client.Authenticate.Default</code>: This message, sent in response to <code>Client.Supports.Set</code>, informs the client of the supported authentication methods:<br />
**<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
***<code>password-credentials</code>: Traditional username/password login.<br />
*** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
*** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
*** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Auth.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Auth.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
* <code>Client.Authenticate.Result</code>: This message, sent in response to <code>Client.Authenticate.Credentials</code>, informs the client of the success or failure of the credentials-based login. <br />
** <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
** <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
'''Client-side:'''<br />
<br />
* <code>Client.Authenticate.Credentials</code>: This message, sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
* <code>Client.Authenticate.OAuth</code>: This message, sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;, ...]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21474Standards:GMCP Authentication2024-02-17T06:50:51Z<p>Vadi: </p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
'''Server-side:'''<br />
<br />
* <code>Client.Authenticate.Default</code>: This message, sent in response to <code>Client.Supports.Set</code>, informs the client of the supported authentication methods:<br />
**<code>type</code>: A string array indicating the supported method(s), which is one or more of:<br />
***<code>password-credentials</code>: Traditional username/password login.<br />
*** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
*** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
*** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Auth.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Auth.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
* <code>Client.Authenticate.Result</code>: This message, sent in response to <code>Client.Authenticate.Credentials</code>, informs the client of the success or failure of the credentials-based login. <br />
** <code>success</code>: (boolean) Indicates whether the authentication attempt was successful.<br />
** <code>message</code>: (string) required string if the login wasn't successful: a human-readable message explaining the result, such as "Invalid credentials" or "Character not found".<br />
<br />
'''Client-side:'''<br />
<br />
* <code>Client.Authenticate.Credentials</code>: This message, sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
* <code>Client.Authenticate.OAuth</code>: This message, sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login. <br />
[[File:GMCP authenticate flow.png|none|thumb|780x780px|Example password flow ([https://gist.github.com/vadi2/6fcc05500823122143a5d45c43915ff0 source])]]<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=File:GMCP_authenticate_flow.png&diff=21473File:GMCP authenticate flow.png2024-02-17T06:48:33Z<p>Vadi: </p>
<hr />
<div>MUD client performs password-based authentication with server, receiving success or failure message.</div>Vadihttps://wiki.mudlet.org/index.php?title=File:Mermaid-diagram-2024-02-17-074552.png&diff=21472File:Mermaid-diagram-2024-02-17-074552.png2024-02-17T06:46:23Z<p>Vadi: </p>
<hr />
<div>MUD client performs password-based authentication with server, receiving success or failure message.</div>Vadihttps://wiki.mudlet.org/index.php?title=File:GMCP_Sample_flow.svg&diff=21471File:GMCP Sample flow.svg2024-02-17T06:44:21Z<p>Vadi: </p>
<hr />
<div>MUD client performs password-based authentication with server, receiving success or failure message.</div>Vadihttps://wiki.mudlet.org/index.php?title=Main_Page&diff=21470Main Page2024-02-17T06:26:42Z<p>Vadi: Add link for GMCP Auth</p>
<hr />
<div><languages/><br />
<!-- BANNER ACROSS TOP OF PAGE --><br />
{| id="mp-topbanner" style="width:100%; background:#fcfcfc; margin-top:1.2em; border:1px solid #ccc;"<br />
| style="width:56%; color:#000;" |<br />
<!-- "WELCOME TO THE MUDLET WIKI" AND ARTICLE COUNT --><br />
{| style="width:280px; border:none; background:none;"<br />
| style="width:280px; text-align:center; white-space:nowrap; color:#000;" |<br />
<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#000;"><translate><!--T:1--> Welcome to the Mudlet Wiki!</translate></div><br />
|}<br />
<!-- BASIC INTRO --><br />
{| id="mp-upper" style="margin:0 0 0 0; background:none;"<br />
| class="MainPageBG" style="width:100%; border:1px solid #c9c07f; background:#c9c07f; vertical-align:top; color:#000;" |<br />
{| id="mp-left" cellpadding="2" cellspacing="5" style="width:100%; vertical-align:top; background:#fdf7bb;"<br />
! <h2 id="mp-tfa-h2" style="margin:0; background:#f4e9bc; font-size:120%; font-weight:bold; border:1px solid #a3b00f; text-align:left; color:#000; padding:0.2em 0.4em;"><translate><!--T:2--> About Mudlet</translate></h2><br />
|-<br />
| style="color:#000;" | <div id="mp-tfa"><br />
<br />
{{TOC right}}<br />
<br />
<translate><br />
<!--T:3--><br />
A cross-platform, open source, and super fast [http://en.wikipedia.org/wiki/Mud_client MUD client] with scripting in [http://en.wikipedia.org/wiki/Lua Lua].<br />
<br />
<!--T:4--><br />
New to Mudlet? Why not start with [http://mudlet.org/media the basics], or take a look at '''[[Special:MyLanguage/Manual:Contents | Mudlet Manual]]'''. or [[Special:MyLanguage/FAQ | Frequently Asked Questions]].<br />
<br />
<!--T:5--><br />
Are you having troubles with Mudlet? We have a bunch of community members that can can help either on our [http://forums.mudlet.org Forums] or [http://mudlet.org/chat Discord].<br />
<br />
<br />
== Download ==<br />
<br />
If you don't have the program yet, [http://www.mudlet.org/download/ download it] - it's free, and works on Windows, macOS, and Linux computers.<br />
<br />
Alternatively, [[Special:MyLanguage/Compiling Mudlet|compile Mudlet]] yourself.<br />
<br />
<br />
== Wiki Links == <!--T:8--><br />
<br />
<!--T:9--><br />
* [[Special:MyLanguage/Manual:Contents | Mudlet Manual]]<br />
** [[Manual:Technical_Manual|Technical Manual]]<br />
*** [[Manual:General Features|General Mudlet features]]<br />
*** [[Manual:Using Variables in Mudlet|Using variables in Mudlet]]<br />
*** [[Manual:Alias Engine|Alias engine]]<br />
*** [[Manual:Trigger Engine|Trigger engine]]<br />
*** [[Manual:Timer Engine|Timer engine]]<br />
*** [[Manual:Event_Engine|Event engine]]<br />
*** [[Manual:Editor|Editor]]<br />
*** [[Manual:Unicode|Unicode]]<br />
*** [[Manual:Mapper|Mapper]]<br />
*** [[Manual:Advanced Lua|Advanced Lua]]<br />
*** [[Manual:Supported Protocols]]<br />
*** [[Manual:Mudlet_Packages|Mudlet packages]]<br />
**** [https://wiki.mudlet.org/w/Category:Mudlet_Package_Listing Wiki Package Listing]<br />
**** [http://forums.mudlet.org/viewforum.php?f=6 Mudlet Packages Forum]<br />
*** [[Manual:Screen_Readers|Screen readers]]<br />
*** [[Manual:Scripting|Scripting]]<br />
*** [[Manual:Best Practices|Best practices]]<br />
*** [[Special:MyLanguage/Manual:Lua Functions | Mudlet Lua API]]<br />
**** [[Manual:Database Functions]]<br />
**** [[Manual:Date/Time Functions]]<br />
**** [[Manual:Discord Functions]]<br />
**** [[Manual:Mapper Functions]]<br />
**** [[Manual:Miscellaneous Functions]]<br />
**** [[Manual:Mudlet Object Functions]]<br />
**** [[Manual:Networking Functions]]<br />
**** [[Manual:String Functions]]<br />
**** [[Manual:Table Functions]]<br />
**** [[Manual:Text to Speech Functions]]<br />
**** [[Manual:UI Functions]]<br />
* [https://www.mudlet.org/geyser/files/geyser/Geyser.html Geyser Reference Docs]<br />
* [[Special:MyLanguage/Translating Mudlet|Translating Mudlet]]<br />
* [[Accessibility]]<br />
<br />
<br />
== MUD standards == <!--T:10--><br />
<br />
<!--T:11--><br />
We will preserve the documentation of MUD standards that may get lost (because the original site is breaking down or is already offline) as they are implemented in Mudlet. We may also look into developing some of them in the future.<br />
* [[Special:MyLanguage/Standards:MMP | MUD Mapping Protocol]]<br />
* [[Special:MyLanguage/Standards:Discord_GMCP | Discord Rich Presence over GMCP]]<br />
* [[Special:MyLanguage/Standards:MUD_Client_Media_Protocol | Mud Client Media Protocol]]<br />
* [[Special:MyLanguage/Standards:GMCP_Authentication | GMCP Authentication]]<br />
<br />
== Learn Lua == <!--T:12--><br />
<br />
<!--T:13--><br />
Mudlet uses Lua for scripting, giving you ways to automate your gaming sessions. Learning Lua is really rewarding - take a look at excellent stuff like:<br />
<br />
* [http://www.lua.org/pil/ Programming in Lua] (official, but might be hard to follow)<br />
* [https://www.youtube.com/playlist?list=PLxgtJR7f0RBKGid7F2dfv7qc-xWwSee2O Learning Lua] (video playlist)<br />
* [https://learnxinyminutes.com/docs/lua/ Learn X in Y minutes - Lua] (if you're familiar with coding already)<br />
* [https://www.youtube.com/watch?v=S4eNl1rA1Ns Learn Lua in an Hour] (video from the same author)<br />
* [https://devhints.io/lua Lua cheatsheet]<br />
* and various [http://lua-users.org/wiki/TutorialDirectory Lua tutorials]<br />
<br />
<br />
== Special Links == <!--T:14--><br />
<br />
<!--T:15--><br />
* [[Special:AllPages | All Pages]]<br />
* [[Special:MyLanguage/Report Spam|Report spam]] if you notice suspicious behavior<br />
<br />
<br />
== Using MediaWiki == <!--T:16--><br />
<br />
<!--T:17--><br />
Interested in contributing to this site? Please do! While first edit will be manually approved (this is to help against spambots), any follow-up edits will show up right away.<br />
<br />
Use the following links to learn more about MediaWiki: (note that the following links are not related to Mudlet)<br />
<br />
<!--T:18--><br />
* [http://www.mediawiki.org/wiki/Help:Formatting Wiki syntax]<br />
* [http://en.wikipedia.org/wiki/Help:Table Wiki table syntax]<br />
<br />
</translate><br />
<br />
|}<br />
|}<br />
|}</div>Vadihttps://wiki.mudlet.org/index.php?title=Standards:GMCP_Authentication&diff=21469Standards:GMCP Authentication2024-02-17T06:25:43Z<p>Vadi: Add GMCP Authentication spec</p>
<hr />
<div>== GMCP Extension for MUD Client Authentication ==<br />
<br />
This document defines a new GMCP extension to enable MUD clients to send credentials and perform authentication using GMCP messages instead of in-band login commands. It also includes optional support for OAuth authorization flows.<br />
<br />
=== Rationale ===<br />
<br />
Different MUDs have diverse login command formats, making it challenging for MUD clients to handle login consistently. This extension provides a standardized way to exchange authentication information through GMCP, simplifying client development and improving compatibility. Additionally, the extension supports OAuth authorization flows, allowing clients to leverage external identity providers for login.<br />
<br />
=== Design ===<br />
<br />
The extension introduces a new namespace called <code>Client.Authenticate</code> with the following commands:<br />
<br />
'''Server-side:'''<br />
<br />
* <code>Client.Authenticate.Default</code>: This message, sent in response to <code>Client.Supports.Set</code>, informs the client of the supported authentication methods:<br />
** <code>type</code>: An array indicating the supported method(s), which is one or more of:<br />
*** <code>password-credentials</code>: Traditional username/password login.<br />
*** <code>oauth-authorization-code</code>: OAuth Authorization Code Grant flow.<br />
*** <code>oauth-PKCE</code>: OAuth Proof Key for Code Exchange flow.<br />
*** <code>oauth-device-code</code>: OAuth Device Code Grant flow.<br />
<br />
Since multiple flows can be supported by a server the <code>type</code> array shall be ordered in the descending order of preference by the server. If the server supports only the credentials flow:<br />
<br />
Client.Auth.Default {"type": ["password-credentials"]}<br />
<br />
If the server supports both Device Code and credentials, specify preference for Device Code with:<br />
<br />
Client.Auth.Default {"type": ["oauth-device-code", "password-credentials"]}<br />
<br />
'''Client-side:'''<br />
<br />
* <code>Client.Authenticate.Credentials</code>: This message, sent after receiving <code>Client.Authenticate.Default</code> with <code>type</code> as <code>password-credentials</code>, sends the character name and password for traditional login.<br />
* <code>Client.Authenticate.OAuth</code>: This message, sent after receiving <code>Client.Authenticate.Default</code>, contains information specific to the chosen OAuth flow (e.g., authorization code, PKCE verifier, etc.). The specific format will be defined in consultation with the community.<br />
<br />
'''Example Flow (Password Credentials):'''<br />
<br />
# Client connects and sends: <code>Core.Supports.Set [&quot;Client.Authenticate 1&quot;]</code><br />
# Server responds with: <code>Client.Authenticate.Default {&quot;type&quot;: [&quot;password-credentials&quot;]}</code><br />
# Client sends: <code>Client.Authenticate.Credentials {&quot;character&quot;: &quot;username&quot;, &quot;password&quot;: &quot;password&quot;}</code><br />
# Server validates credentials and performs login.<br />
<br />
'''OAuth Flows:'''<br />
<br />
Specific details for each supported OAuth flow will be defined in separate documents. These documents will outline the message formats and server-side logic for handling each flow.<br />
<br />
=== Implementation Considerations ===<br />
<br />
* This extension should be implemented according to the GMCP protocol specifications.<br />
* Messages should be well-formatted JSON objects.<br />
* Servers should validate incoming authentication information securely.<br />
* Clients should handle potential errors and server responses gracefully.<br />
<br />
=== Conclusion ===<br />
<br />
This GMCP extension provides a standardized and flexible approach to MUD client authentication, improving compatibility and enabling support for OAuth authorization flows. By adopting this extension, MUD developers and client developers can simplify login processes and enhance user experience.<br />
<br />
'''Note:''' This is a draft proposal, and further community input and refinement may be necessary before finalizing the specification. Additionally, the specific details of OAuth flow support require input from the community to be defined.</div>Vadihttps://wiki.mudlet.org/index.php?title=Manual:Mudlet_Packages&diff=20915Manual:Mudlet Packages2024-02-11T07:20:52Z<p>Vadi: /* as a one-liner */ mention module CLI install path</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet packages - what they are and how to install / make them}}<br />
= What is a Mudlet package =<br />
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.<br />
<br />
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).<br />
<br />
== Where to find Mudlet packages ==<br />
Check out the [https://forums.mudlet.org/viewforum.php?f=6 Scripts & Packages] section on Mudlet forums for an excellent selection of Mudlet packages.<br />
<br />
Some Mudlet packages may also be exlusively available on your own game-specific website or forums, so make sure to check out what your game has to offer as well.<br />
<br />
== What is a Mudlet module ==<br />
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.<br />
<br />
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.<br />
<br />
If you'd like your module to be loaded before all the scripts in a Mudlet profile, you can do that with the <code>-1</code> module priority.<br />
<br />
== How to install a Mudlet package ==<br />
=== as a package ===<br />
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.<br />
<br />
Alternatively, Toolbox→Package Manager will open the window where you can hit 'Install'.<br />
<br />
=== as a one-liner ===<br />
In the command line as a package:<br />
<br />
<code>lua installPackage("https://<online package location>")</code><br />
<br />
In the command line as a module:<br />
<br />
<code>lua installModule("https://<online package location>")</code><br />
<br />
=== as a module ===<br />
Use Toolbox→Module Manager to install a module.<br />
<br />
=== from the game ===<br />
<br />
Packages can also be auto-installed from the MUD server via ATCP or GMCP - see [[Manual:ATCP_Extensions|ATCP extensions]] or [[Manual:GMCP_Extensions|GMCP extensions]] for more.<br />
<br />
== Module best practices ==<br />
<br />
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]]<br />
<br />
There are some decisions you can make that are outside of best practices, but will influence things:<br />
<br />
* write all code inside Mudlet, or outside Mudlet in .lua files?<br />
** 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.<br />
** If you want the power of a full IDE or dislike XML diffs in your SCM, then use the latter, see [https://github.com/demonnic/muddler muddler, an unofficial tool for Mudlet packages].<br />
<br />
== Create a Mudlet package with Mudlet Profile Exporter ==<br />
<br />
Mudlet provides an export dialog for saving a subset of a profile's settings and configuration to a file.<br />
<br />
Exported settings are saved into a package that can be imported using ''Package Manager > Install new package''.<br />
<br />
[[File:ProfileExport-Start-Button.png|frameless|Toolbox → Packages arrow]]<br />
[[File:ProfileExport-Start-Menu.png|frameless|upright=0.58|System Toolbox menu]]<br />
<br />
=== Package information ===<br />
<br />
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.<br />
<br />
To build a Mudlet package following best practices, use the Package optional details by pressing '''(optional) add icon, description, and more''' to define additional metadata and provide information to Mudlet users that choose to import your package.<br />
<br />
[[File:ProfileExport-Form-Name.png|frameless|]]<br />
<br />
=== Package optional details ===<br />
<br />
[[File:ProfileExport-Form-Options.png|frameless|Make your package stand out]]<br />
<br />
The optional details allow setting:<br />
<br />
* Author information<br />
<br />
* An icon, 512x512 recommended<br />
<br />
* A description for those interested in learning more, and documenting any features or a short changelog<br />
<br />
* A version number<br />
<br />
You can use [https://guides.github.com/features/mastering-markdown/ 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 [https://packagecontrol.io/ here] and [https://marketplace.visualstudio.com/ here].<br />
<br />
=== External data, dependencies ===<br />
<br />
If your package requires other Mudlet packages, add them under the Required packages dropdown.<br />
For example creating a set of custom triggers for a game to use with ''generic_mapper''.<br />
<br />
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.<br />
Without these files the package may work locally but not on another's computer.<br />
<br />
To remove an included asset, select it from the list and use backspace (fn + delete on macOS) to remove it.<br />
<br />
'''NOTE:''' To remove a dependency that has already been selected and added, use CTRL+Delete (Linux/Windows) or FN+Backspace (MacOS).<br />
<br />
[[File:ProfileExport-Form-References.png|frameless|Include any dependencies]]<br />
<br />
=== Save exported profile ===<br />
<br />
Mudlet will put the exported package on the current user's desktop by default.<br />
Use ''Select export location'' to pick a different destination. <br />
<br />
'''Export''' to write the package, '''Close''' to exit<br />
<br />
[[File:ProfileExport-Form-Export.png|frameless|Set the .mpackage path]]<br />
<br />
== Create a Mudlet package by hand ==<br />
<br />
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.<br />
<br />
=== Naming the package ===<br />
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:<br />
<br />
<syntaxhighlight lang="lua"><br />
mpackage = "<name of your package>"<br />
</syntaxhighlight><br />
<br />
That's it. If you don't include config.lua, Mudlet will then deduce the package name from the file name.<br />
<br />
=== Including images, sounds, and other files ===<br />
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.<br />
<br />
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:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you don't have to worry about \ versus / for file paths - use / everywhere, Lua will make it work on Windows fine<br />
<br />
setBackgroundImage("my health label", getMudletHomeDir().."/sipper/health.png")<br />
</syntaxhighlight><br />
<br />
Install the one-liner package demo above for an example of how to make use of images in packages.<br />
<br />
=== Using .lua files ===<br />
As of Mudlet 3.6.2 you can <code>require "myfile"</code> to load myfile.lua from the package folder.<br />
<br />
As an example, if you have your package '''sipper''', using a custom echo function named '''sipperecho''' defined in '''customFunctions.lua''' you can<br />
<br />
<syntaxhighlight lang="lua"><br />
require "sipper.customFunctions"<br />
<br />
sipperecho("I work")<br />
</syntaxhighlight><br />
<br />
Alternatively you can rename '''customFunctions.lua''' to '''init.lua''', this will allow you to <code>require "<name of your package>"</code> and<br />
<br />
<syntaxhighlight lang="lua"><br />
require "sipper"<br />
<br />
sipperecho("I work")<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20914Compiling Mudlet2024-02-10T20:17:37Z<p>Vadi: /* Compiling on Chrome OS */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
# Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. <br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20913Compiling Mudlet2024-02-10T20:16:35Z<p>Vadi: /* Compiling on Chrome OS */ Update for Debian 12</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \<br />
qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
# Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. <br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20912Compiling Mudlet2024-02-10T11:42:26Z<p>Vadi: /* Compiling on macOS */ Adjust the Boost installation to ensure that the CMake configuration functions correctly on macOS within Visual Studio Code.</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install boost<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
# Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. <br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).<br />
<br />
= Compile Time Flags =<br />
<br />
<nowiki><br />
DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding<br />
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing<br />
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings<br />
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding<br />
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.<br />
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".<br />
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...<br />
</nowiki></div>Vadihttps://wiki.mudlet.org/index.php?title=Release_Checklist&diff=20895Release Checklist2024-02-01T06:49:35Z<p>Vadi: /* Mudlet release checklist */</p>
<hr />
<div>= Mudlet release checklist =<br />
# 5 days before the release (14 if it's a long one)<br />
## ☐ [automated] update <code>mudlet.ts</code> with the latest translations strings for translators to translate<br />
## ☐ [automated] update <code>mudlet_en_US.ts</code> with the latest translation strings, translate/update the few plural forms it contains as necessary and then generate the binary translation <code>mudlet_en_US.qm</code> file and merge it into the repo (see [https://wiki.mudlet.org/w/Translating_Mudlet#English_.28American.29_translation Translating Mudlet - English (American) translation]).<br />
## ☐ [automated] update [http://www.mudlet.org/geyser/files/index.html Geyser docs]<br />
## ☐ [automated] update built-in packages and scripts (IRE mapping script, ...)<br />
## ☐ [automated] update edbee to latest in our fork, and the subsequent submodule<br />
## ☐ merge outstanding approved pull requests<br />
## ☐ update Patreon supporters in About tab<br />
## ☐ create a new <code>release-<version></code> branch off <code>development</code><br />
### everything above this step can be done concurrently.<br />
## ☐ create the next milestone in github if it doesn't exist already<br />
## ☐ go through every single commit (in main repo and installers) and ensure all new functionality is documented<br />
## ☐ check all [https://github.com/Mudlet/Mudlet/issues?q=is%3Aissue+is%3Aopen+label%3Aregression regressions] to see if any must be fixed before the release<br />
## ☐ go through every single commit and write up a relese post with the latest highlights - and save it as a github milestone draft<br />
### everything above this step can be done concurrently, while 13, 14, and 15 below must be done sequentially.<br />
## ☐ wait a day for PTBs to get built<br />
## ☐ after the PTBs have been built, announce start of testing in Discord channel #mudlet-testing with the list of additions/improvements/fixes (but not infrastructure), and add link to latest download builds (from [https://make.mudlet.org/snapshots Latest Branch Snapshots], but double check that sha matches [https://github.com/Mudlet/Mudlet/commits/development the latest commit]).<br />
## ☐ get testers to sign off (via Discord reaction) that they tested the release and it is fine with them<br />
### if a tester doesn't sign off for 2 releases, notify them, if they don't do it on the next one, remove them from the testers team<br />
# on release day<br />
## ☐ merge latest translations from Crowdin<br />
## ☐ merge all Area 51 functions into main wiki<br />
## ☐ [https://wiki.mudlet.org/w/Manual:Lua_Functions?action=purge purge] Lua_Functions cache to ensure the latest functions are visible<br />
## ☐ merge [[Update_lua_function_list|latest autocomplete json]]<br />
### everything above this step can be done concurrently, while everything below this step must be done sequentially.<br />
## ☐ create a new release in the 'release' channel in [https://www.dblsqd.com/user/apps/30a30c47-b1cd-48fe-b93e-ab9041b88323 dblsqd]. Make sure to enter the changelog right away, as it cannot be edited after. Include the full version number and a link to the release post ([[Media:Creating a new Mudlet release.png|example]]). A [https://www.npmjs.com/package/dblsqd-cli command-line variant] of this is: <code>dblsqd release -a mudlet -c release -m "<message>. <a href="https://mudlet.org/4-##">See the changelog</a>." <version, ie 4.11.0></code><br />
## ☐ update mudlet.pro and CMakeLists.txt to new version and strip out BUILD to be empty in release branch (release process starts here)<br />
## ☐ tag release in git and push<br />
## ☐ manually create source code package [https://github.com/Mudlet/Mudlet/blob/33ad832253d6b6411d7c1132e68455742157d60d/CI/travis.linux.after_success.sh#L144 following this]<br />
## ☐ reset BUILD in release branch to be -dev<br />
## ☐ wait for the builds to complete...<br />
## ☐ test that all binaries launch and work<br />
## ☐ manually upload artifacts to https://www.mudlet.org/wp-content/files/?C=M;O=D through webmin. Linux and macOS ones will be available as artifacts on the Github job, while Windows is an artifact on the Appveyor job.<br />
## ☐ manually link uploaded artifacts to dblsqd (see [1])<br />
## ☐ update [https://github.com/Mudlet/Mudlet/blob/development/.github/repo-metadata.yml repo-metadata.yml] to the next release version<br />
## ☐ close current github milestone<br />
## ☐ [[Howto:Update Downloads|update downloads on mudlet.org]]<br />
## ☐ [automated] create changelog with [https://github.com/Mudlet/Mudlet/actions/workflows/generate-changelog.yml a github action]<br />
## ☐ create a proper github release using the draft created earlier<br />
## ☐ [automated] insert list of translators into the release post ([https://www.mudlet.org/thank-translators/crowdin.php tool])<br />
## ☐ [automated] insert list of coders into the release post ([https://github.com/Mudlet/Mudlet/actions/workflows/generate-coder-attribution.yml tool])<br />
## ☐ publish release post and it will be automatically posted to mudlet.org on save<br />
## ☐ delay rest of announcements until 3-4 days past the release; post when there are no verified issues in update<br />
### everything above the step must be done sequentially, while everything below this step can be done concurrently.<br />
## ☐ post to #announcements in Discord. Publish the post, then add a follow-up @everyone tag as a separate post. This will notify folks in the Mudlet server without showing the @everyone tag in all other syncronised servers<br />
## ☐ post news to https://launchpad.net/mudlet<br />
## ☐ post news to opencollective https://opencollective.com/mudlet/updates<br />
## ☐ post thread on forums.mudlet.org<br />
## ☐ post update on achaea, starmourn, imperian, lusternia, pkuxkx.net, [http://linux.softpedia.com/get/GAMES-ENTERTAINMENT/MUD/Mudlet-45973.shtml softpedia]<br />
## ☐ post update on twitter, reddit, http://arkadia.rpg.pl, muder.ru<br />
## ☐ email to releaseradar@github.com about the update<br />
## ☐ submit mudlet windows installer to avg and avast whitelisting<br />
## ☐ update Linux distro maintainers, [https://chocolatey.org/packages/mudlet/ContactOwners Chocolatey maintainer], flag package outdated on arch<br />
## ☐ merge <code>development</code> into <code>master</code> branch<br />
## ☐ merge, don't squash or rebase, the release branch into development (but don't delete right away, keep it around for a potential hotfix if needed. Delete after the next release is done). Do it right away so next day's PTB's versions is the new release.<br />
## ☐ [https://www.mudlet.org/2021/10/trial-pay-out-to-popular-prs/ create polls] for most popular changes<br />
<br />
<br />
[1]:<br />
<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach linux:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-linux-x64.AppImage.tar"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach mac:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>.dmg"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach win:x86 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-windows-installer.exe"<br />
<br />
<br />
= Individual contributor TODOs =<br />
* keneanung: https://github.com/users/keneanung/projects/1<br />
* vadi2: https://gist.github.com/vadi2/c4dd137010c1b969c011293eddfcee73<br />
<br />
[[Category: Mudlet Admin Manual]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20881Compiling Mudlet2024-01-28T23:11:23Z<p>Vadi: /* Compiling on macOS */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Lua & Luarocks =<br />
<br />
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) Lua] (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at [https://wiki.mudlet.org/w/Manual:Lua_Functions Mudlet Lua API] as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.<br />
<br />
Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively [https://en.wikipedia.org/wiki/C_(programming_language) 'C']) source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as '''rocks''' from the public [https://en.wikipedia.org/wiki/LuaRocks Luarocks] collection. Such a rock actually consists of a ''rockspec'' file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in '''''each''''' running Mudlet ''profile'') can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the ''require'' command.<br />
<br />
Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the ''lua-yajl'' module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 22.04===<br />
Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
sudo luarocks install lrexlib-pcre<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Other Ubuntu Versions===<br />
<br />
Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older<br />
Qt versions, have a look at [https://launchpad.net/~beineri Stephan Binners PPAs], which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and<br />
usage instructions as Qt is installed to /opt and requires sourcing a script to set up.<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip ZIP_DIR=`brew --prefix libzip`<br />
<br />
brew install p7zip<br />
export BOOST_ROOT="$(pwd)/../Mudlet/3rdparty/boost"<br />
export BOOST_URL="https://sourceforge.net/projects/boost/files/boost/1.83.0/boost_1_83_0.tar.bz2/download"<br />
mkdir -p $BOOST_ROOT<br />
curl --progress-bar --location --output $BOOST_ROOT/download.tar.bz2 $BOOST_URL<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar.bz2 -y -bd<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar -y -bd<br />
cd $BOOST_ROOT && cp -r boost_*/* .<br />
rm -rf boost_*/* download.tar.bz2 download.tar<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
====== 7. Troubleshooting ======<br />
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then <code>./configure && sudo make install</code>.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
'''4. (Optional) Discord library'''<br />
<br />
If you get the following error;<br />
<br />
Could not find Discord library - searched in:<br />
<br />
you need to specify the discord library in your build. Run the following, changing the path where necessary;<br />
<br />
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/mudlet-dev/Mudlet/3rdparty/discord/rpc/lib/<br />
<br />
and recompile. You should see<br />
<br />
Discord integration loaded. Using functions from: "libdiscord-rpc.so"<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on Arch Linux ==<br />
<br />
===AUR Install and Compile===<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].<br />
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile Manual install].)<br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
===Manual Install and Compile===<br />
These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo pacman -S --needed cmake qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \<br />
ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo lua5.1 /usr/bin/luarocks install lcf<br />
sudo lua5.1 /usr/bin/luarocks install luautf8<br />
sudo lua5.1 /usr/bin/luarocks install lua-yajl<br />
sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre<br />
sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3<br />
sudo lua5.1 /usr/bin/luarocks install lua-zip<br />
<br />
There is an optional dependency for discord integration:<br />
git clone https://github.com/discord/discord-rpc<br />
cd discord-rpc<br />
mkdir build<br />
cd build<br />
cmake .. -DCMAKE_INSTALL_PREFIX=/usr<br />
sudo cmake --build . --config Release --target install<br />
<br />
'''2. obtaining the source code'''<br />
<br />
Obtain the latest in-development code with:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
'''4. installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''5. optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo pacman -S install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
== Compiling on Fedora (aarch64) ==<br />
<br />
'''1. Install dependencies'''<br />
sudo dnf groupinstall "Development Tools" "Development Libraries"<br />
<br />
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel<br />
<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luazip<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lcf<br />
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl<br />
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre<br />
In your user's home directory:<br />
<br />
If you use a bash shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .bashenv<br />
source .bashenv<br />
If you use a zsh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .zshenv<br />
source .zshenv<br />
If you use a csh shell:<br />
luarocks --lua-version 5.1 path --no-bin >> .cshenv<br />
source .cshenv<br />
This should cover paths, but you may want to reboot to be sure.<br />
<br />
'''2. Obtain the source code'''<br />
git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki><br />
mkdir Mudlet/build<br />
cd Mudlet/src<br />
<br />
'''3. Make necessary compiling instruction adjustments'''<br />
<br />
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:<br />
linux {<br />
LIBS += \<br />
-llua5.1 \<br />
-lhunspell<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:<br />
linux {<br />
LIBS += \<br />
-llua-5.1 \<br />
-lhunspell-1.7<br />
INCLUDEPATH += /usr/include/lua5.1<br />
}<br />
Save and exit.<br />
<br />
'''4. Compile'''<br />
cd ../build<br />
Run this in the build directory:<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro<br />
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:<br />
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share<br />
Adding build variables to mudlet.pro so that it finds the correct libraries:<br />
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1<br />
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.<br />
LUA_SEARCH_OUT=lua-5.1<br />
Once complete, run the following:<br />
<br />
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):<br />
make<br />
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):<br />
make -j `nproc`<br />
Or if you want something in between, make -j `nproc` tells it to use all available processor cores. If you want to use a specific number instead (ie 2), you can use:<br />
make -j 2<br />
<br />
'''5. Install'''<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
'''6. Hang onto the cloned git repo '''<br />
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
# Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. <br />
<br />
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! <br />
<br />
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
'''3. Watch the magic happen'''<br />
<br />
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
[https://github.com/features/codespaces/ Github Codespaces] allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.<br />
<br />
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in CLion, adjust the CMake settings:<br />
<br />
[[File:Clion_cmake_settings.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).</div>Vadihttps://wiki.mudlet.org/index.php?title=Release_Checklist&diff=20880Release Checklist2024-01-28T21:12:43Z<p>Vadi: Improve chronological ordering and mention which steps can be done concurrently or sequentially</p>
<hr />
<div>= Mudlet release checklist =<br />
# 5 days before the release (14 if it's a long one)<br />
## ☐ [automated] update <code>mudlet.ts</code> with the latest translations strings for translators to translate<br />
## ☐ [automated] update <code>mudlet_en_US.ts</code> with the latest translation strings, translate/update the few plural forms it contains as necessary and then generate the binary translation <code>mudlet_en_US.qm</code> file and merge it into the repo (see [https://wiki.mudlet.org/w/Translating_Mudlet#English_.28American.29_translation Translating Mudlet - English (American) translation]).<br />
## ☐ [automated] update [http://www.mudlet.org/geyser/files/index.html Geyser docs]<br />
## ☐ [automated] update built-in packages and scripts (IRE mapping script, ...)<br />
## ☐ [automated] update edbee to latest in our fork, and the subsequent submodule<br />
## ☐ merge outstanding approved pull requests<br />
## ☐ update Patreon supporters in About tab<br />
## ☐ create a new <code>release-<version></code> branch off <code>development</code><br />
### everything above this step can be done concurrently.<br />
## ☐ create the next milestone in github if it doesn't exist already<br />
## ☐ go through every single commit (in main repo and installers) and ensure all new functionality is documented<br />
## ☐ check all [https://github.com/Mudlet/Mudlet/issues?q=is%3Aissue+is%3Aopen+label%3Aregression regressions] to see if any must be fixed before the release<br />
## ☐ go through every single commit and write up a relese post with the latest highlights - and save it as a github milestone draft<br />
### everything above this step can be done concurrently, while 13, 14, and 15 below must be done sequentially.<br />
## ☐ wait a day for PTBs to get built<br />
## ☐ after the PTBs have been built, announce start of testing in Discord channel #mudlet-testing with the list of additions/improvements/fixes (but not infrastructure), and add link to latest download builds (from [https://make.mudlet.org/snapshots Latest Branch Snapshots], but double check that sha matches [https://github.com/Mudlet/Mudlet/commits/development the latest commit]).<br />
## ☐ get testers to sign off (via Discord reaction) that they tested the release and it is fine with them<br />
### if a tester doesn't sign off for 2 releases, notify them, if they don't do it on the next one, remove them from the testers team<br />
# on release day<br />
## ☐ merge latest translations from Crowdin<br />
## ☐ merge all Area 51 functions into main wiki<br />
## ☐ [https://wiki.mudlet.org/w/Manual:Lua_Functions?action=purge purge] Lua_Functions cache to ensure the latest functions are visible<br />
## ☐ merge [[Update_lua_function_list|latest autocomplete json]]<br />
### everything above this step can be done concurrently, while everything below this step must be done sequentially.<br />
## ☐ create a new release in the 'release' channel in [https://www.dblsqd.com/user/apps/30a30c47-b1cd-48fe-b93e-ab9041b88323 dblsqd]. Make sure to enter the changelog right away, as it cannot be edited after. Include the full version number and a link to the release post ([[Media:Creating a new Mudlet release.png|example]]). A [https://www.npmjs.com/package/dblsqd-cli command-line variant] of this is: <code>dblsqd release -a mudlet -c release -m "<message>. <a href="https://mudlet.org/4-##">See the changelog</a>." <version, ie 4.11.0></code><br />
## ☐ update mudlet.pro and CMakeLists.txt to new version and strip out BUILD to be empty in release branch (release process starts here)<br />
## ☐ tag release in git and push<br />
## ☐ manually create source code package [https://github.com/Mudlet/Mudlet/blob/33ad832253d6b6411d7c1132e68455742157d60d/CI/travis.linux.after_success.sh#L144 following this]<br />
## ☐ reset BUILD in release branch to be -dev<br />
## ☐ wait for the builds to complete...<br />
## ☐ manually upload artifacts to https://www.mudlet.org/wp-content/files/?C=M;O=D through webmin. Linux and macOS ones will be available as artifacts on the Github job, while Windows is an artifact on the Appveyor job.<br />
## ☐ manually link uploaded artifacts to dblsqd[1]:<br />
## ☐ test that all binaries launch and work<br />
## ☐ update [https://github.com/Mudlet/Mudlet/blob/development/.github/repo-metadata.yml repo-metadata.yml] to the next release version<br />
## ☐ close current github milestone<br />
## ☐ [[Howto:Update Downloads|update downloads on mudlet.org]]<br />
## ☐ [automated] create changelog with [https://github.com/Mudlet/Mudlet/actions/workflows/generate-changelog.yml a github action]<br />
## ☐ create a proper github release using the draft created earlier<br />
## ☐ [automated] insert list of translators into the release post ([https://www.mudlet.org/thank-translators/crowdin.php tool])<br />
## ☐ [automated] insert list of coders into the release post ([https://github.com/Mudlet/Mudlet/actions/workflows/generate-coder-attribution.yml tool])<br />
## ☐ publish release post and it will be automatically posted to mudlet.org on save<br />
## ☐ delay rest of announcements until 3-4 days past the release; post when there are no verified issues in update<br />
### everything above the step must be done sequentially, while everything below this step can be done concurrently.<br />
## ☐ post to #announcements in Discord. Publish the post, then add a follow-up @everyone tag as a separate post. This will notify folks in the Mudlet server without showing the @everyone tag in all other syncronised servers<br />
## ☐ post news to https://launchpad.net/mudlet<br />
## ☐ post thread on forums.mudlet.org<br />
## ☐ post update on achaea, starmourn, imperian, lusternia, pkuxkx.net, [http://linux.softpedia.com/get/GAMES-ENTERTAINMENT/MUD/Mudlet-45973.shtml softpedia]<br />
## ☐ post update on twitter, reddit, http://arkadia.rpg.pl, muder.ru<br />
## ☐ email to releaseradar@github.com about the update<br />
## ☐ submit mudlet windows installer to avg and avast whitelisting<br />
## ☐ update Linux distro maintainers, [https://chocolatey.org/packages/mudlet/ContactOwners Chocolatey maintainer], flag package outdated on arch<br />
## ☐ merge <code>development</code> into <code>master</code> branch<br />
## ☐ merge, don't squash or rebase, the release branch into development (but don't delete right away, keep it around for a potential hotfix if needed. Delete after the next release is done). Do it right away so next day's PTB's versions is the new release.<br />
## ☐ [https://www.mudlet.org/2021/10/trial-pay-out-to-popular-prs/ create polls] for most popular changes<br />
<br />
<br />
[1]:<br />
<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach linux:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-linux-x64.AppImage.tar"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach mac:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>.dmg"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach win:x86 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-windows-installer.exe"<br />
<br />
<br />
= Individual contributor TODOs =<br />
* keneanung: https://github.com/users/keneanung/projects/1<br />
* vadi2: https://gist.github.com/vadi2/c4dd137010c1b969c011293eddfcee73<br />
<br />
[[Category: Mudlet Admin Manual]]</div>Vadihttps://wiki.mudlet.org/index.php?title=User:Molideus&diff=20758User:Molideus2024-01-12T22:25:26Z<p>Vadi: /* mapSymbolFontInfo */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions that manipulate the mapper and its related features.}}<br />
= Mapper Functions =<br />
These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the game you're playing. For a collection of pre-made scripts and general mapper talk, visit the [http://forums.mudlet.org/viewforum.php?f=13 mapper section] of the forums.<br />
<br />
To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:<br />
<syntaxhighlight lang="lua"><br />
mudlet = mudlet or {}; mudlet.mapper_script = true<br />
</syntaxhighlight><br />
<br />
==addAreaName==<br />
;areaID = addAreaName(areaName)<br />
<br />
:Adds a new area name and returns the new (positive) area ID for the new name. If the name already exists, older versions of Mudlet returned -1 though since 3.0 the code will return ''nil'' and an error message.<br />
: See also: [[#deleteArea|deleteArea()]], [[#addRoom|addRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local newId, err = addAreaName("My House")<br />
<br />
if newId == nil or newId < 1 or err then<br />
echo("That area name could not be added - error is: ".. err.."\n")<br />
else<br />
cecho("<green>Created new area with the ID of "..newId..".\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==addCustomLine==<br />
;addCustomLine(roomID, id_to, direction, style, color, arrow)<br />
: See also: [[#getCustomLines|getCustomLines()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to attach the custom line to.<br />
* ''id_to:''<br />
: EITHER: a room Id number, of a room on same area who's x and y coordinates are used as the other end of a SINGLE segment custom line (it does NOT imply that is what the exit it represent goes to, just the location of the end of the line);<br />
: OR: a table of sets of THREE (x,y and z) coordinates in that order, x and y can be decimals, z is an integer ('''and must be present and be the same for all points on the line''', though it is irrelevant to what is produced as the line is drawn on the same z-coordinate as the room that the line is attached to!)<br />
* ''direction:'' a string to associate the line with a valid exit direction, "n", "ne", "e", "se", "s", "sw", "w", "nw", "up", "down", "in" or "out" or a special exit (before Mudlet 3.17 this was case-sensitive and cardinal directions had to be uppercase).<br />
* ''style:'' a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.<br />
* ''color:'' a table of three integers between 0 and 255 as the custom line color as the red, green and blue components in that order.<br />
* ''arrow:'' a boolean which if true will set the custom line to have an arrow on the end of the last segment.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- create a line from roomid 1 to roomid 2<br />
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)<br />
<br />
addCustomLine(1, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
</syntaxhighlight><br />
<br />
A bigger example that'll create a new area and the room in it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local areaid = addAreaName("my first area")<br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
setRoomArea(newroomid, "my first area")<br />
setRoomCoordinates(newroomid, 0, 0, 0)<br />
<br />
local otherroomid = createRoomID()<br />
addRoom(otherroomid)<br />
setRoomArea(otherroomid, "my first area")<br />
setRoomCoordinates(otherroomid, 0, 5, 0)<br />
<br />
addSpecialExit(newroomid, otherroomid, "climb Rope")<br />
addCustomLine(newroomid, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)<br />
<br />
centerview(newroomid)<br />
</syntaxhighlight><br />
<br />
==addMapEvent==<br />
;addMapEvent(uniquename, event name, parent, display name, arguments)<br />
<br />
:Adds a new entry to an existing mapper right-click entry. You can add one with addMapMenu. If there is no display name, it will default to the unique name (which otherwise isn't shown and is just used to differentiate this entry from others). ''event name'' is the Mudlet event that will be called when this is clicked on, and ''arguments'' will be passed to the handler function.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn") <br />
</syntaxhighlight><br />
The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.<br />
<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Room type")<br />
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")<br />
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")<br />
<br />
function onMapMarkSelectedRooms(event, markRoomType)<br />
local selectedRooms = getMapSelection()["rooms"]<br />
for i, val in ipairs(selectedRooms) do<br />
if markRoomType == "markRoomsAsDeathTrap" then<br />
local r, g, b = unpack(color_table.black)<br />
--death trap<br />
setRoomEnv(val, 300)<br />
--death traps Env<br />
setCustomEnvColor(300, r, g, b, 255)<br />
setRoomChar(val, "☠️")<br />
lockRoom(val, true)<br />
elseif markRoomType == "markRoomsAsOneRoom" then<br />
local r, g, b = unpack(color_table.LightCoral)<br />
--single-pass<br />
setRoomEnv(val, 301)<br />
--one room Env<br />
setCustomEnvColor(301, r, g, b, 255)<br />
setRoomChar(val, "🚹")<br />
end<br />
end<br />
updateMap()<br />
end<br />
<br />
registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")<br />
</syntaxhighlight><br />
This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"<br />
<br />
==addMapMenu==<br />
;addMapMenu(uniquename, parent, display name)<br />
<br />
:Adds a new submenu to the right-click menu that opens when you right-click on the mapper. You can then add more submenus to it, or add entries with [[#addMapEvent|addMapEvent()]].<br />
: See also: [[#addMapEvent|addMapEvent()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will create a menu named: Favorites.<br />
addMapMenu("Favorites")<br />
<br />
-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.<br />
addMapMenu("Favorites1234343", "Favorites", "More Favorites") <br />
</syntaxhighlight><br />
<br />
==addRoom==<br />
;addRoom(roomID)<br />
<br />
:Creates a new room with the given ID, returns true if the room was successfully created. <br />
<br />
{{note}} If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with [[#createRoomID|createRoomID()]] and associating your room IDs with Mudlets via [[#setRoomIDbyHash|setRoomIDbyHash()]] and [[#getRoomIDbyHash|getRoomIDbyHash()]]. The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge.<br />
{{note}} Creating your own mapping script? Check out more [[Manual:Mapper#Making_your_own_mapping_script|information here]].<br />
<br />
: See also: [[#createRoomID|createRoomID()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
</syntaxhighlight><br />
<br />
==addSpecialExit==<br />
;addSpecialExit(roomIDFrom, roomIDTo, moveCommand)<br />
<br />
:Creates a one-way from one room to another, that will use the given command for going through them.<br />
<br />
: See also: [[#clearSpecialExits|clearSpecialExits()]], [[#removeSpecialExit|removeSpecialExit()]], [[#setExit|setExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command<br />
addSpecialExit(1, 2, "pull rope")<br />
</syntaxhighlight><br />
<br />
Example in an alias:<br />
<syntaxhighlight lang="lua"><br />
-- sample alias pattern: ^spe (\d+) (.*?)$<br />
-- currentroom is your current room ID in this example<br />
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])<br />
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])<br />
centerview(currentroom)<br />
</syntaxhighlight><br />
<br />
==auditAreas==<br />
;auditAreas()<br />
<br />
: Initiates a consistency check on the whole map: All rooms, areas, and their composition. This is also done automatically whenever you first open your map, so probably seldom necessary to do manually. Will output findings to screen and/or logfile for later review.<br />
<br />
: See also: [[#saveMap|saveMap()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
==centerview==<br />
;centerview (roomID)<br />
<br />
:Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.<br />
<br />
: See also: [[#getPlayerRoom|getPlayerRoom()]], [[#updateMap|updateMap()]]<br />
<br />
==clearAreaUserData==<br />
;clearAreaUserData(areaID)<br />
<br />
; Parameter<br />
* areaID - ID number for area to clear.<br />
<br />
:Clears all user data from a given area. Note that this will not touch the room user data.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#clearRoomUserData|clearRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearAreaUserData(34))<br />
-- I did have data in that area, so it returns:<br />
true<br />
<br />
display(clearAreaUserData(34))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearAreaUserDataItem==<br />
;clearAreaUserDataItem(areaID, key)<br />
<br />
:Removes the specific key and value from the user data from a given area.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#clearAreaUserData|clearAreaUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
true<br />
<br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapSelection==<br />
;clearMapSelection()<br />
<br />
:Clears any selected rooms from the map (i.e. they are highlighted in orange).<br />
<br />
:Returns true if rooms are successfully cleared, false if nothing selected or cleared.<br />
<br />
: See also [[#getMapSelection|getMapSelection()]]<br />
<br />
==clearMapUserData==<br />
;clearMapUserData()<br />
<br />
:Clears all user data stored for the map itself. Note that this will not touch the area or room user data.<br />
<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserData|clearAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearMapUserData())<br />
-- I did have user data stored for the map, so it returns:<br />
true<br />
<br />
display(clearMapUserData())<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapUserDataItem==<br />
;clearMapUserDataItem(mapID, key)<br />
<br />
:Removes the specific key and value from the user data from the map user data.<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearMapUserData|clearMapUserData()]], [[#clearAreaRoomUserData|clearAreaRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
last_modified = "1483228799"<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
true<br />
<br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearRoomUserData==<br />
;clearRoomUserData(roomID)<br />
<br />
:Clears all user data from a given room.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{note}} Returns a boolean true if any data was removed from the specified room and false if there was nothing to erase since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearRoomUserData(3441))<br />
-- I did have data in that room, so it returns:<br />
true<br />
<br />
display(clearRoomUserData(3441))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearRoomUserDataItem==<br />
;clearRoomUserDataItem(roomID, key)<br />
<br />
:Removes the specific key and value from the user data from a given room.<br />
:Returns a boolean true if data was found against the give key in the user data for the given room and it is removed, will return false if exact key not present in the data. Returns nil if the room for the roomID not found.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
true<br />
<br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearSpecialExits==<br />
;clearSpecialExits(roomID) <br />
<br />
:Removes all special exits from a room.<br />
: See also: [[#addSpecialExit|addSpecialExit()]], [[#removeSpecialExit|removeSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
clearSpecialExits(1337)<br />
<br />
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example<br />
echo("All special exits successfully cleared from 1337.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==closeMapWidget==<br />
;closeMapWidget()<br />
:closes (hides) the map window (similar to clicking on the map icon)<br />
<br />
{{MudletVersion|4.7}}<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
==connectExitStub==<br />
;connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])<br />
<br />
:Connects existing rooms with matching exit stubs. If you only give it a roomID and a direction, it'll work out which room should be linked to it that has an appropriate opposite exit stub and is located in the right direction. You can also just specify from and to room IDs, and it'll smartly use the right direction to link in. Lastly, you can specify all three arguments - fromID, toID and the direction (in that order) if you'd like to be explicit, or use [[#setExit|setExit()]] for the same effect.<br />
<br />
;Parameters<br />
* ''fromID:''<br />
: Room ID to set the exit stub in.<br />
* ''direction:''<br />
: You can either specify the direction to link the room in, and/or a specific room ID (see below). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
* ''toID:''<br />
: The room ID to link this room to. If you don't specify it, the mapper will work out which room should be logically linked.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- try and connect all stubs that are in a room<br />
local stubs = getExitStubs(roomID)<br />
if stubs then<br />
for i,v in pairs(stubs) do<br />
connectExitStub(roomID, v)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==createMapLabel==<br />
;labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])<br />
<br />
:Creates a text label on the map at given coordinates, with the given background and foreground colors. It can go above or below the rooms, scale with zoom or stay a static size. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a script can reduce the size of the saved map somewhat. It returns a label ID that you can use later for deleting it.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
<br />
: See also: [[#getMapLabel|getMapLabel()]], [[#getMapLabels|getMapLabels()]], [[#deleteMapLabel|deleteMapLabel]], [[#createMapUmageLabel|createMapImageLabel()]]<br />
<br />
{{note}} Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID where to put the label.<br />
* ''text:''<br />
: The text to put into the label. To get a multiline text label add a '\n' between the lines.<br />
* ''posX, posY, posZ:''<br />
: Position of the label in (floating point numbers) room coordinates.<br />
* ''fgRed, fgGreen, fgBlue:''<br />
: Foreground color or text color of the label.<br />
* ''bgRed, bgGreen, bgBlue:''<br />
: Background color of the label.<br />
* ''zoom:''<br />
: (optional) Zoom factor of the label if noScaling is false. Higher zoom will give higher resolution of the text and smaller size of the label. Default is 30.0.<br />
* ''fontSize:''<br />
: (optional, but needed if zoom is provided) Size of the font of the text. Default is 50.<br />
* ''showOnTop:''<br />
: (optional) If true the label will be drawn on top of the rooms and if it is false the label will be drawn as a background, defaults to true if not given.<br />
* ''noScaling:''<br />
: (optional) If true the label will have the same size when you zoom in and out in the mapper, If it is false the label will scale when you zoom the mapper, defaults to true if not given.<br />
* ''fontName:''<br />
: (optional) font name to use.<br />
* ''foregroundTransparency''<br />
: (optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.<br />
* ''backgroundTransparency''<br />
: (optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.<br />
* ''temporary''<br />
: (optional, from Mudlet version 4.17.0) if true does not save the image that the label makes in map save files, defaults to false if not given, or for prior versions of Mudlet.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area<br />
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB<br />
-- zoom is only relevant when when you're using a label of a static size, so we use 0<br />
-- and we use a font size of 20 for our label, which is a small medium compared to the map<br />
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)<br />
<br />
-- to create a multi line text label we add '\n' between lines<br />
-- the position is placed somewhat to the northeast of the center of the map<br />
-- this label will be scaled as you zoom the map.<br />
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)<br />
<br />
local x,y,z = getRoomCoordinates(getPlayerRoom())<br />
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)<br />
</syntaxhighlight><br />
<br />
==createMapImageLabel==<br />
;labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])<br />
<br />
:Creates an image label on the map at the given coordinates, with the given dimensions and zoom. You might find the default room and image size correlation to be too big - try reducing the width and height of the image then, while also zooming in the same amount. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a external file available when the map file is loaded, can avoid expanding the size of the saved map considerably.<br />
<br />
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.<br />
: See also: [[#createMapLabel|createMapLabel]], [[#deleteMapLabel|deleteMapLabel]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- 138 is our pretend area ID<br />
-- next, inside [[]]'s, is the exact location of our image<br />
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map<br />
-- 482 is the width of the image - we divide it by 100 to scale it down, and then we'll zoom it by 100 - making the image take up about 4 rooms in width then<br />
-- 555 is the original height of the image<br />
-- 100 is how much we zoom it by, 1 would be no zoom<br />
-- false to make it go below our rooms<br />
-- (from 4.17.0) true to not save the label's image in the map file afterwards<br />
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)<br />
</syntaxhighlight><br />
<br />
==createMapper==<br />
;createMapper([name of userwindow], x, y, width, height)<br />
<br />
:Creates a miniconsole window for the mapper to render in, the with the given dimensions. You can only create one mapper at a time, and it is not currently possible to have a label on or under the mapper - otherwise, clicks won't register.<br />
<br />
{{note}} ''name of userwindow'' available in Mudlet 4.6.1+<br />
<br />
{{Note}} If this command is ''not'' used then clicking on the Main Toolbar's '''Map''' button will create a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Map''' button will toggle between showing and hiding the map whether it was created using the ''createMapper'' function or as a dock-able widget.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet<br />
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- another example:<br />
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})<br />
<br />
local mapper = Geyser.Mapper:new({<br />
name = "mapper",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, main)<br />
</syntaxhighlight><br />
<br />
==createRoomID==<br />
;usableId = createRoomID([minimumStartingRoomId])<br />
<br />
:Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs. <br />
<br />
;Parameters<br />
* ''minimumStartingRoomId'' (optional, available in Mudlet 3.0+):<br />
: If provided, specifies a roomID to start searching for an empty one at, instead of 1. Useful if you'd like to ensure certain areas have specific room number ranges, for example. If you you're working with a huge map, provide the last used room ID to this function for an available roomID to be found a lot quicker.<br />
<br />
: See also: [[#addRoom|addRoom()]]<br />
<br />
==deleteArea==<br />
;deleteArea(areaID or areaName)<br />
<br />
:Deletes the given area and all rooms in it. Returns ''true'' on success or ''nil'' + ''error message'' otherwise.<br />
: See also: [[#addAreaName|addAreaName()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to delete, or:<br />
* ''areaName'' (available in Mudlet 3.0+):<br />
: Area name to delete.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete by areaID<br />
deleteArea(23)<br />
-- or since Mudlet 3.0, by area name<br />
deleteArea("Big city")<br />
</syntaxhighlight><br />
<br />
==deleteMap==<br />
;deleteMap()<br />
<br />
Deletes the entire map. This may be useful whilst initially setting up a mapper package for a new Game to clear faulty map data generated up to this point.<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
{{MudletVersion|4.14.0}}<br />
<br />
;Returns<br />
:''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result - which will be the "blank" screen with a warning message of the form ''"No rooms in the map - load another one, or start mapping from scratch to begin."''<br />
<br />
{{note}} Prior to the introduction of this function, the recommended method to achieve the same result was to use [[#loadMap|loadMap()]] with a non-existent file-name, such as ''"_"'' however that would also cause an ''"[ ERROR ]"'' type message to appear on the profile's main console.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMap()<br />
</syntaxhighlight><br />
<br />
==deleteMapLabel==<br />
;deleteMapLabel(areaID, labelID)<br />
<br />
:Deletes a map label from a specific area.<br />
: See also: [[#createMapLabel|createMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMapLabel(50, 1)<br />
</syntaxhighlight><br />
<br />
==deleteRoom==<br />
;deleteRoom(roomID)<br />
<br />
:Deletes an individual room, and unlinks all exits leading to and from it.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteRoom(335)<br />
</syntaxhighlight><br />
<br />
==disableMapInfo==<br />
;disableMapInfo(label)<br />
<br />
Disable the particular map info - same as toggling off checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be disabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==enableMapInfo==<br />
;enableMapInfo(label)<br />
<br />
Enable the particular map info - same as toggling on checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be enabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#disableMapInfo|disableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==getAllAreaUserData==<br />
;dataTable = getAllAreaUserData(areaID)<br />
<br />
:Returns all the user data items stored in the given area ID; will return an empty table if there is no data stored or nil if there is no such area with that ID.<br />
<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
--might result in:--<br />
{<br />
country = "Andor",<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllMapUserData==<br />
;dataTable = getAllMapUserData()<br />
<br />
:Returns all the user data items stored at the map level; will return an empty table if there is no data stored.<br />
<br />
: See also: [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
--might result in:--<br />
{<br />
description = [[This map is about so and so game]],<br />
author = "Bob",<br />
["last updated"] = "December 5, 2020"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllRoomEntrances==<br />
;exitsTable = getAllRoomEntrances(roomID)<br />
<br />
:Returns an indexed list of normal and special exits leading into this room. In case of two-way exits, this'll report exactly the same rooms as [[#getRoomExits|getRoomExits()]], but this function has the ability to pick up one-way exits coming into the room as well.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- print the list of rooms that have exits leading into room 512<br />
for _, roomid in ipairs(getAllRoomEntrances(512)) do <br />
print(roomid)<br />
end<br />
</syntaxhighlight><br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
==getAllRoomUserData==<br />
;dataTable = getAllRoomUserData(roomID)<br />
<br />
:Returns all the user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
;See also: [[#getRoomUserDataKeys|getRoomUserDataKeys()]] - for a related command that only returns the data keys.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
--might result in:--<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
</syntaxhighlight><br />
<br />
==getAreaExits==<br />
;roomTable = getAreaExits(areaID, showExits)<br />
<br />
: Returns a table (indexed or key-value) of the rooms in the given area that have exits leading out to other areas - that is, border rooms.<br />
<br />
;See also: [[#setExit|setExit()]], [[#getRoomExits|getRoomExits()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to list the exits for.<br />
* ''showExits:''<br />
: Boolean argument, if true then the exits that lead out to another area will be listed for each room.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- list all border rooms for area 44:<br />
getAreaExits(44)<br />
<br />
-- returns:<br />
--[[<br />
{<br />
7091,<br />
10659,<br />
11112,<br />
11122,<br />
11133,<br />
11400,<br />
12483,<br />
24012<br />
}<br />
]]<br />
<br />
-- list all border rooms for area 44, and the exits within them that go out to other areas:<br />
getAreaExits(44, true)<br />
--[[<br />
{<br />
[12483] = {<br />
north = 27278<br />
},<br />
[11122] = {<br />
["enter grate"] = 14551<br />
},<br />
[11112] = {<br />
["enter grate"] = 14829<br />
},<br />
[24012] = {<br />
north = 22413<br />
},<br />
[11400] = {<br />
south = 10577<br />
},<br />
[11133] = {<br />
["enter grate"] = 15610<br />
},<br />
[7091] = {<br />
down = 4411<br />
},<br />
[10659] = {<br />
["enter grate"] = 15510<br />
}<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
==getAreaRooms==<br />
;getAreaRooms(area id)<br />
<br />
:Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or ''nil'' if no such area exists. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- using the sample findAreaID() function defined in the getAreaTable() example, <br />
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID<br />
function echoRoomList(areaname)<br />
local id, msg = findAreaID(areaname)<br />
if id then<br />
local roomlist, endresult = getAreaRooms(id), {}<br />
<br />
-- obtain a room list for each of the room IDs we got<br />
for _, id in pairs(roomlist) do<br />
endresult[id] = getRoomName(id)<br />
end<br />
<br />
-- now display something half-decent looking<br />
cecho(string.format(<br />
"List of all rooms in %s (%d):\n", msg, table.size(endresult)))<br />
<br />
for roomid, roomname in pairs(endresult) do<br />
cecho(string.format(<br />
"%6s: %s\n", roomid, roomname))<br />
end<br />
elseif not id and msg then<br />
echo("ID not found; " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTable==<br />
;areaTable = getAreaTable()<br />
<br />
:Returns a key(area name)-value(area id) table with all known areas and their IDs. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
;See also: [[#getAreaTableSwap|getAreaTableSwap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example function that returns the area ID for a given area<br />
<br />
function findAreaID(areaname)<br />
local list = getAreaTable()<br />
<br />
-- iterate over the list of areas, matching them with substring match. <br />
-- if we get match a single area, then return it's ID, otherwise return<br />
-- 'false' and a message that there are than one are matches<br />
local returnid, fullareaname<br />
for area, id in pairs(list) do<br />
if area:find(areaname, 1, true) then<br />
if returnid then return false, "more than one area matches" end<br />
returnid = id; fullareaname = area<br />
end<br />
end<br />
<br />
return returnid, fullareaname<br />
end<br />
<br />
-- sample use:<br />
local id, msg = findAreaID("blahblah")<br />
if id then<br />
echo("Found a matching ID: " .. id)<br />
elseif not id and msg then<br />
echo("ID not found: " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTableSwap==<br />
;areaTable = getAreaTableSwap()<br />
<br />
:Returns a key(area id)-value(area name) table with all known areas and their IDs. Unlike getAreaTable which won't show you all areas with the same name by different IDs, this function will. <br />
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.<br />
<br />
==getAreaUserData==<br />
;dataValue = getAreaUserData(areaID, key)<br />
<br />
:Returns a specific data item stored against the given key for the given area ID number. This is very like the corresponding Room User Data command but intended for per area rather than for per room data (for storage of data relating to the whole map see the corresponding Map User Data commands.) <br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or a Lua ''nil'' and an error message if the key is not present in the Area User Data for the given Area ID. Use [[#setAreaUserData|setAreaUserData()]] function for storing the user data.<br />
<br />
;See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAreaUserData(34, "country"))<br />
-- might produce --<br />
"Andor"<br />
</syntaxhighlight><br />
<br />
==getCustomEnvColorTable==<br />
;envcolors = getCustomEnvColorTable()<br />
<br />
:Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
{<br />
envid1 = {r, g, b, alpha},<br />
envid2 = {r, g, b, alpha}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines==<br />
;lineTable = getCustomLines(roomID)<br />
: See also: [[#addCustomLine|addCustomLine()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Returns a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the custom line details of.<br />
<br />
{{MudletVersion|3.0.}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = {<br />
b = 0,<br />
g = 128,<br />
r = 128<br />
},<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = {<br />
{<br />
y = 9.5,<br />
x = 4.5<br />
},<br />
{<br />
y = 9.5,<br />
x = 6<br />
},<br />
[0] = {<br />
y = 5.5,<br />
x = 4.5<br />
}<br />
}<br />
},<br />
N = {<br />
attributes = {<br />
color = {<br />
b = 255,<br />
g = 255,<br />
r = 0<br />
},<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = {<br />
[0] = {<br />
y = 27,<br />
x = -3<br />
}<br />
}<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines1==<br />
;lineTable = getCustomLines1(roomID)<br />
This is a replacement for ''getCustomLines(...)'' that outputs the tables for the coordinates for the points on the custom line in an order and format that can be fed straight back into an ''addCustomLine(...)'' call; similarly the color parameters are also reported in the correct format to also be reused in the same manner. This function is intended to make it simpler for scripts to manipulate such lines.<br />
:See also: [[Manual:Mapper_Functions#addCustomLine|addCustomLine()]], [[Manual:Mapper_Functions#removeCustomLine|removeCustomLine()]], [[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]<br />
{{MudletVersion| 4.16}}<br />
<br />
;Parameters<br />
* ''roomID:''<br />
:Room ID to return the custom line details of.<br />
<br />
;Returns<br />
:a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines1(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = { 128, 128, 0 },<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } } <br />
},<br />
N = {<br />
attributes = {<br />
color = { 0, 255, 255 },<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = { { -3, 27, 3 } }<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getDoors==<br />
;doors = getDoors(roomID)<br />
<br />
:Returns a key-value table with the cardinal direction as the key and the door value as a number. If there are no doors in a room, it returns an empty table.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to check for doors in.<br />
<br />
: See also: [[#setDoor|setDoor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example that displays possible doors in room 2334<br />
local doors = getDoors(2334)<br />
<br />
if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end<br />
<br />
local door_status = {"open", "closed", "locked"}<br />
<br />
for direction, door in pairs(doors) do<br />
cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")<br />
end<br />
</syntaxhighlight><br />
<br />
==getExitStubs==<br />
;stubs = getExitStubs(roomid)<br />
<br />
:Returns an indexed table (starting at 0) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#connectExitStub|connectExitStub()]], [[#getExitStubs1|getExitStubs1()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
local stubs = getExitStubs(6)<br />
for i = 0, #stubs do print(stubs[i]) end<br />
</syntaxhighlight><br />
<br />
{{note}} Previously would throw a lua error on non-existent room - now returns nil plus error message (as does other run-time errors) - previously would return just a nil on NO exit stubs but now returns a notification error message as well, to aide disambiguation of the nil value.<br />
<br />
==getExitStubs1==<br />
;stubs = getExitStubs1(roomid)<br />
<br />
:Returns an indexed table (starting at 1) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. As this function starts indexing from 1 as it is default in Lua, you can use ipairs() to iterate over the results.<br />
<br />
; See also: [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end<br />
</syntaxhighlight><br />
<br />
==getExitWeights==<br />
;weights = getExitWeights(roomid)<br />
<br />
:Returns a key-value table of the exit weights that a room has, with the direction or special exit as a key and the value as the exit weight. If a weight for a direction wasn't yet set, it won't be listed.<br />
<br />
;Parameters<br />
* ''roomid:''<br />
: Room ID to view the exit weights in.<br />
<br />
: See also: [[#setExitWeight|setExitWeight()]]<br />
<br />
==getGridMode==<br />
;TrueOrFalse = getGridMode(areaID)<br />
<br />
:Use this to see, if a specific area has grid/wilderness view mode set. This way, you can also calculate from a script, how many grid areas a map has got in total.<br />
<br />
{{MudletVersion|3.11}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID (number) to view the grid mode of.<br />
<br />
: See also: [[#setGridMode|setGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getGridMode(55)<br />
-- will return: false<br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
getGridMode(55)<br />
-- will return: true<br />
</syntaxhighlight><br />
<br />
==getMapEvents==<br />
; mapevents = getMapEvents()<br />
<br />
: Returns a list of map events currently registered. Each event is a dictionary with the keys ''uniquename'', ''parent'', ''event name'', ''display name'', and ''arguments'', which correspond to the arguments of ''addMapEvent()''.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")<br />
<br />
local mapEvents = getMapEvents()<br />
for _, event in ipairs(mapEvents) do<br />
echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.3}}<br />
<br />
==getMapLabel==<br />
;labelinfo = getMapLabel(areaID, labelID or labelText)<br />
<br />
:Returns a key-value table describing that particular label in an area. Keys it contains are the ''X'', ''Y'', ''Z'' coordinates, ''Height'' and ''Width'', ''BgColor'', ''FgColor'', ''Pixmap'', and the ''Text'' it contains. If the label is an image label, then ''Text'' will be set to the ''no text'' string.<br />
<br />
:''BgColor'' and ''FgColor'' are tables with ''r'',''g'',''b'' keys, each holding ''0-255'' color component value.<br />
<br />
:''Pixmap'' is base64 encoded image of label.<br />
<br />
{{note}} ''BgColor'', ''FgColor'', ''Pixmap'' are available in Mudlet 4.11+<br />
<br />
;Parameters <br />
* ''areaID:'' areaID from which to retrieve label<br />
* ''labelID:'' labelID (''getMapLabels'' return table key) or labelText (exact match)<br />
<br />
See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabels|getMapLabels()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua getMapLabels(52)<br />
{<br />
"no text",<br />
[0] = "test"<br />
}<br />
<br />
lua getMapLabel(52, 0)<br />
{<br />
Y = -2,<br />
X = -8,<br />
Z = 11,<br />
Height = 3.9669418334961,<br />
Text = "test",<br />
Width = 8.6776866912842,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
<br />
lua getMapLabel(52, "no text")<br />
{<br />
Y = 8,<br />
X = -15,<br />
Z = 11,<br />
Height = 7.2520666122437,<br />
Text = "no text"<br />
Width = 11.21900844574,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapLabels==<br />
;arealabels = getMapLabels(areaID)<br />
<br />
:Returns an indexed table (that starts indexing from 0) of all of the labels in the area, plus their label text. You can use the label id to [[#deleteMapLabel|deleteMapLabel()]] it.<br />
:If there are no labels in the area at all, it will return an empty table.<br />
<br />
: See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabel|getMapLabel()]], [[#deleteMapLabel|deleteMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapLabels(43))<br />
table {<br />
0: ''<br />
1: 'Waterways'<br />
}<br />
<br />
deleteMapLabel(43, 0)<br />
display(getMapLabels(43))<br />
table {<br />
1: 'Waterways'<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapMenus==<br />
;getMapMenus()<br />
<br />
:Returns a table with the available map menus as key-value in the format of <code>map menu - parent item</code>. If an item is positioned at the menu's top-level, the value will say <code>top-level</code>.<br />
:If you haven't opened a map yet, getMapMenus() will return nil+error message. If you don't have any map labels yet, an empty table <code>{}</code> is returned.<br />
<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- given the following menu structure:<br />
top-level<br />
menu1<br />
menu1.1<br />
action1.1.1<br />
menu1.2<br />
action1.2.1<br />
menu2<br />
<br />
getMapMenus() -- will return:<br />
{<br />
menu2 = "top-level",<br />
menu1.2 = "menu1",<br />
menu1.1 = "menu1",<br />
menu1 = "top-level"<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapSelection==<br />
; getMapSelection()<br />
<br />
:Returns a table containing details of the current mouse selection in the 2D mapper.<br />
<br />
:Reports on one or more rooms being selected (i.e. they are highlighted in orange).<br />
<br />
:The contents of the table will vary depending on what is currently selected. If the selection is of map rooms then there will be keys of ''center'' and ''rooms'': the former will indicates the center room (the one with the yellow cross-hairs) if there is more than one room selected or the only room if there is only one selected (there will not be cross-hairs in that case); the latter will contain a list of the one or more rooms.<br />
<br />
; Example - several rooms selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5011,<br />
5012,<br />
5013,<br />
5014,<br />
5018,<br />
5019,<br />
5020<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - one room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5013<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - no or something other than a room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==getMapUserData==<br />
;getMapUserData( key )<br />
<br />
;Parameters<br />
* ''key:''<br />
: string used as a key to select the data stored in the map as a whole.<br />
<br />
:Returns the user data item (string); will return a nil+error message if there is no data with such a key in the map data.<br />
<br />
: See also: [[#getAllMapUserData|getAllMapUserData()]], [[#setMapUserData|setMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapUserData("last updated"))<br />
--might result in:--<br />
"December 5, 2020"<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getMapZoom==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''4.17.0''''' also with the option to get the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet remembering the zoom level last used for each area and with the revision of the ''setMapZoom()'' function to also take an areaID to work on instead of the current area being viewed in the map.<br />
<br />
:See also: [[Manual:Mapper_Functions#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| 4.17.0}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is ''3.0'' and the initial value - and what prior Mudlet versions started each session with - is ''20.0''.<br />
<br />
==getPath==<br />
;getPath(roomID from, roomID to)<br />
<br />
:Returns a boolean true/false if a path between two room IDs is possible. If it is, the global ''speedWalkDir'' table is set to all of the directions that have to be taken to get there, and the global ''speedWalkPath'' table is set to all of the roomIDs you'll encounter on the way, and as of 3.0, ''speedWalkWeight'' will return all of the room weights. Additionally returns the total cost (all weights added up) of the path after the boolean argument in 3.0.<br />
<br />
<br />
: See also: [[Manual:Lua_Functions#translateTable|translateTable()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if we can go to room 155 from room 34 - if yes, go to it<br />
if getPath(34,155) then<br />
gotoRoom(155)<br />
else<br />
echo("\nCan't go there!")<br />
end<br />
</syntaxhighlight><br />
<br />
==getPlayerRoom==<br />
;getPlayerRoom()<br />
<br />
:Returns the current player location as set by [[#centerview|centerview()]].<br />
<br />
: See also: [[#centerview|centerview]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("We're currently in " .. getRoomName(getPlayerRoom()))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.14}}<br />
<br />
==getRoomArea==<br />
;getRoomArea(roomID)<br />
<br />
:Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by [[#getAreaTable | getAreaTable()]] function, or use the [[#getRoomAreaName |getRoomAreaName()]] function.<br />
<br />
{{note}} If the room ID does not exist, this function will raise an error.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Area ID of room #100 is: "..getRoomArea(100))<br />
<br />
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))<br />
</syntaxhighlight><br />
<br />
==getRoomAreaName==<br />
;getRoomAreaName(areaID or areaName)<br />
<br />
:Returns the area name for a given area id; or the area id for a given area name.<br />
<br />
{{note}} Despite the name, this function will not return the area name for a given ''room'' id (or room name) directly. However, renaming or revising it would break existing scripts.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))<br />
</syntaxhighlight><br />
<br />
<br />
==getRoomChar==<br />
;getRoomChar(roomID)<br />
<br />
:Returns the single ASCII character that forms the ''symbol'' for the given room id.<br />
<br />
: '''Since Mudlet version 3.8 :''' this facility has been extended:<br />
: Returns the string (UTF-8) that forms the ''symbol'' for the given room id; this may have been set with either [[#setRoomChar|setRoomChar()]] or with the ''symbol'' (was ''letter'' in prior versions) context menu item for rooms in the 2D Map.<br />
<br />
==getRoomCharColor==<br />
;r,g,b = getRoomCharColor(roomID)<br />
<br />
:Returns the color of the Room Character as a set of r,g,b color coordinates.<br />
<br />
;See also: [[Manual:Lua_Functions#setRoomCharColor|setRoomCharColor()]], [[Manual:Lua_Functions#getRoomChar|getRoomChar()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room ID to get the room character color from<br />
<br />
;Returns <br />
* The color as 3 separate numbers, red, green, and blue from 0-255<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0<br />
local r,g,b = getRoomCharColor(12345)<br />
decho(f"Room Character for room 12345 is <{r},{g},{b}>this color.<r> It is made up of <{r},0,0>{r} red<r>, <0,{g},0>{g} green<r>, <0,0,{b}> {b} blue<r>.\")<br />
</syntaxhighlight><br />
<br />
==getRoomCoordinates==<br />
;x,y,z = getRoomCoordinates(roomID)<br />
<br />
:Returns the room coordinates of the given room ID.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local x,y,z = getRoomCoordinates(roomID)<br />
echo("Room Coordinates for "..roomID..":")<br />
echo("\n X:"..x)<br />
echo("\n Y:"..y)<br />
echo("\n Z:"..z)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- A quick function that will find all rooms on the same z-position in an area; this is useful if, say, you want to know what all the same rooms on the same "level" of an area is.<br />
function sortByZ(areaID, zval)<br />
local area = getAreaRooms(areaID)<br />
local t = {}<br />
for _, id in ipairs(area) do<br />
local _, _, z = getRoomCoordinates(id)<br />
if z == zval then<br />
table.insert(t, id)<br />
end<br />
end<br />
return t<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomEnv==<br />
;envID = getRoomEnv(roomID)<br />
<br />
:Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function checkID(id)<br />
echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))<br />
end<br />
</syntaxhighlight><br />
<br />
== getRoomExits ==<br />
;getRoomExits (roomID)<br />
:Returns the currently known non-special exits for a room in an key-index form: ''exit = exitroomid''.<br />
<br />
: See also: [[#getSpecialExits|getSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
table {<br />
'northwest': 80<br />
'east': 78<br />
}<br />
</syntaxhighlight><br />
<br />
Here's a practical example that queries the rooms around you and searched for one of the water environments (the number would depend on how it was mapped):<br />
<br />
<syntaxhighlight lang="lua"><br />
local exits = getRoomExits(mycurrentroomid)<br />
for direction,num in pairs(exits) do<br />
local env_num = getRoomEnv(num)<br />
if env_num == 22 or env_num == 20 or env_num == 30 then<br />
print("There's water to the "..direction.."!")<br />
end<br />
end</syntaxhighlight><br />
<br />
==getRoomHashByID==<br />
;getRoomHashByID(roomID)<br />
<br />
:Returns a room hash that is associated with a given room ID in the mapper. This is primarily for games that make use of hashes instead of room IDs. It may be used to share map data while not sharing map itself. ''nil'' is returned if no room is not found.<br />
<br />
: See also: [[#getRoomIDbyHash|getRoomIDbyHash()]]<br />
{{MudletVersion|3.13.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
for id,name in pairs(getRooms()) do<br />
local h = getRoomUserData(id, "herbs")<br />
if h ~= "" then<br />
echo(string.format([[["%s"] = "%s",]], getRoomHashByID(id), h))<br />
echo("\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomIDbyHash==<br />
;roomID = getRoomIDbyHash(hash)<br />
<br />
:Returns a room ID that is associated with a given hash in the mapper. This is primarily for games that make use of hashes instead of room IDs (like [http://avalon.mud.de/index.php?enter=1 Avalon.de]). ''-1'' is returned if no room ID matches the hash.<br />
<br />
: See also: [[#getRoomHashByID|getRoomHashByID()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177<br />
local id = getRoomIDbyHash("5dfe55b0c8d769e865fd85ba63127fbc")<br />
if id == -1 then <br />
id = createRoomID()<br />
setRoomIDbyHash(id, "5dfe55b0c8d769e865fd85ba63127fbc")<br />
addRoom(id)<br />
setRoomCoordinates(id, 0, 0, -1)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomName==<br />
;getRoomName(roomID)<br />
<br />
:Returns the room name for a given room id.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("The name of the room id #455 is %s.", getRoomName(455))<br />
</syntaxhighlight><br />
<br />
==getRooms==<br />
;rooms = getRooms()<br />
<br />
:Returns the list of '''all''' rooms in the map in the whole map in roomid - room name format.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- simple, raw viewer for rooms in the world<br />
display(getRooms())<br />
<br />
-- iterate over all rooms in code<br />
for id,name in pairs(getRooms()) do<br />
print(id, name)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomsByPosition==<br />
;roomTable = getRoomsByPosition(areaID, x,y,z)<br />
<br />
:Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.<br />
<br />
{{note}} The returned table starts indexing from '''0''' and not the usual lua index of '''1''', which means that using '''#''' to count the size of the returned table will produce erroneous results - use [[Manual:Table_Functions#table.size|table.size()]] instead.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sample alias to determine a room nearby, given a relative direction from the current room<br />
<br />
local otherroom<br />
if matches[2] == "" then<br />
local w = matches[3]<br />
local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)<br />
local has = table.contains<br />
if has({"west", "left", "w", "l"}, w) then<br />
x = (x or ox) - 1; y = (y or oy); z = (z or oz)<br />
elseif has({"east", "right", "e", "r"}, w) then<br />
x = (x or ox) + 1; y = (y or oy); z = (z or oz)<br />
elseif has({"north", "top", "n", "t"}, w) then<br />
x = (x or ox); y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"south", "bottom", "s", "b"}, w) then<br />
x = (x or ox); y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"northwest", "topleft", "nw", "tl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"northeast", "topright", "ne", "tr"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"southeast", "bottomright", "se", "br"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"up", "u"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) + 1<br />
elseif has({"down", "d"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) - 1<br />
end<br />
<br />
local carea = getRoomArea(mmp.currentroom)<br />
if not carea then mmp.echo("Don't know what area are we in.") return end<br />
<br />
otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))<br />
<br />
if not otherroom then<br />
mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return<br />
else<br />
mmp.echo("The room "..w.." of us has an ID of "..otherroom)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomUserData==<br />
;getRoomUserData(roomID, key)<br />
<br />
:Returns the user data value (string) stored at a given room with a given key (string), or "" if none is stored. Use [[#setRoomUserData|setRoomUserData()]] function for setting the user data.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserData(341, "visitcount"))<br />
</syntaxhighlight><br />
<br />
:;getRoomUserData(roomID, key, enableFullErrorReporting)<br />
<br />
::Returns the user data value (string) stored at a given room with a given key (string), or, if the boolean value ''enableFullErrorReporting'' is true, ''nil'' and an error message if the key is not present or the room does not exist; if ''enableFullErrorReporting'' is false an empty string is returned but then it is not possible to tell if that particular value is actually stored or not against the given key.<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<!-- I would like this block to be indented to match the Example header but the mark-up system seems to be broken and only includes the first line<br />
if the start of the code line begins: ":<lua>..."--><br />
<syntaxhighlight lang="lua">local vNum = 341<br />
result, errMsg = getRoomUserData(vNum, "visitcount", true)<br />
if result ~= nil then<br />
display(result)<br />
else<br />
echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")<br />
end</syntaxhighlight><br />
<br />
==getRoomUserDataKeys==<br />
;getRoomUserDataKeys(roomID)<br />
<br />
:Returns all the keys for user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserDataKeys(3441))<br />
--might result in:--<br />
{<br />
"description",<br />
"doorname_up",<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getRoomWeight==<br />
;getRoomWeight(roomID)<br />
<br />
:Returns the weight of a room. By default, all new rooms have a weight of 1.<br />
: See also: [[#setRoomWeight|setRoomWeight()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Original weight of room 541: "..getRoomWeight(541))<br />
setRoomWeight(541, 3)<br />
display("New weight of room 541: "..getRoomWeight(541))<br />
</syntaxhighlight><br />
<br />
==getSpecialExits==<br />
;exits = getSpecialExits(roomID[, listAllExits])<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the special exits of.<br />
* ''listAllExits:''<br />
: (Since ''TBA'') In the case where there is more than one special exit to the same room ID list all of them.<br />
<br />
:Returns a roomid table of sub-tables containing name/command and exit lock status, of the special exits in the room. If there are no special exits in the room, the table returned will be empty.<br />
:Before ''TBA'' (likely to be Mudlet version '''4.11.0'''), if more than one special exit goes to the ''same'' exit room id then one of those exits is returned at random. Since ''TBA'' this will be the best (i.e. lowest-weight) exit that is '''not''' locked; should none be unlocked then the lowest locked one will be listed. In case of a tie, one of the tying exits will be picked at random.<br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- There are three special exits from 1337 to the room 42:<br />
-- "climb down ladder" which is locked and has an exit weight of 10<br />
-- "step out window" which is unlocked and has an exit weight of 20<br />
-- "jump out window" which is unlocked and has an exit weight of 990<br />
getSpecialExits(1337)<br />
<br />
-- In 4.10.1 and before this could results in:<br />
table {<br />
42 = {"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"climb down ladder" = "1"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA this will return:<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA, with the second argument as true, this gives:<br />
getSpecialExits(1337, true)<br />
table {<br />
42 = {"step out window" = "0",<br />
"climb down ladder" = "1",<br />
"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
</syntaxhighlight><br />
<br />
==getSpecialExitsSwap==<br />
;getSpecialExitsSwap(roomID)<br />
<br />
:Very similar to [[#getSpecialExits|getSpecialExits()]] function, but returns the rooms in the command - roomid style.<br />
<br />
==gotoRoom==<br />
;gotoRoom (roomID)<br />
:Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".<br />
<br />
In case this isn't working, and you are coding your own mapping script, [[Manual:Mapper#Making_your_own_mapping_script|see here]] how to implement additional functionality necessary.<br />
<br />
==hasExitLock==<br />
;status = hasExitLock(roomID, direction)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
-- check if the east exit of room 1201 is locked<br />
display(hasExitLock(1201, 4))<br />
display(hasExitLock(1201, "e"))<br />
display(hasExitLock(1201, "east"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#lockExit|lockExit()]]<br />
<br />
==hasSpecialExitLock==<br />
;hasSpecialExitLock(from roomID, to roomID, moveCommand)<br />
<br />
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. ''moveCommand'' is the action to take to get through the gate.<br />
<br />
See also: [[#lockSpecialExit|lockSpecialExit()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command<br />
lockSpecialExit(17463, 7814, 'enter feather', true)<br />
<br />
-- see if it is locked: it will say 'true', it is<br />
display(hasSpecialExitLock(17463, 7814, 'enter feather'))<br />
</syntaxhighlight><br />
<br />
==highlightRoom==<br />
;highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)<br />
<br />
:Highlights a room with the given color, which will override its environment color. If you use two different colors, then there'll be a shading from the center going outwards that changes into the other color. <br />
<br />
;Parameters<br />
* ''roomID''<br />
: ID of the room to be colored.<br />
* ''color1Red, color1Green, color1Blue''<br />
: RGB values of the first color.<br />
* ''color2Red, color2Green, color2Blue''<br />
: RGB values of the second color.<br />
* ''highlightRadius'' <br />
: The radius for the highlight circle - if you don't want rooms beside each other to overlap, use ''1'' as the radius. <br />
* ''color1Alpha'' and ''color2Alpha'' <br />
: Transparency values from 0 (completely transparent) to 255 (not transparent at all).<br />
<br />
: See also: [[#unHighlightRoom|unHighlightRoom()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- color room #351 red to blue<br />
local r,g,b = unpack(color_table.red)<br />
local br,bg,bb = unpack(color_table.blue)<br />
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)<br />
</syntaxhighlight><br />
<br />
==killMapInfo==<br />
;killMapInfo(label)<br />
<br />
Delete a map info contributor entirely - it will be not available anymore.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be removed was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==loadJsonMap==<br />
; loadJsonMap(pathFileName)<br />
<br />
; Parameters:<br />
<br />
* ''pathFileName'' a string that is an absolute path and file name to read the data from.<br />
<br />
Load the Mudlet map in text (JSON) format. It does take longer than loading usual map file (''.dat'' in binary) so it will show a progress dialog.<br />
<br />
: See also: [[#saveJsonMap|saveJsonMap()]]<br />
<br />
Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11.0}}<br />
<br />
==loadMap==<br />
;loadMap(file location)<br />
<br />
:Loads the map file from a given location. The map file must be in Mudlet's format - saved with [[#saveMap|saveMap()]] or, as of the Mudlet 3.0 may be a MMP XML map conforming to the structure used by I.R.E. for their downloadable maps for their MUD games. <br />
<br />
:Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.<br />
<br />
:Using no arguments will load the last saved map.<br />
<br />
<syntaxhighlight lang="lua"><br />
loadMap("/home/user/Desktop/Mudlet Map.dat")<br />
</syntaxhighlight><br />
<br />
{{Note}} A file name ending with <code>.xml</code> will indicate the XML format.<br />
<br />
==lockExit==<br />
;lockExit(roomID, direction, lockIfTrue)<br />
<br />
:Locks a given exit from a room. The destination may remain accessible through other paths, unlike [[#lockRoom|lockRoom]]. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").<br />
<br />
: See also: [[#hasExitLock|hasExitLock()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- lock the east exit of room 1201 so we never path through it<br />
lockExit(1201, 4, true)<br />
</syntaxhighlight><br />
<br />
==lockRoom==<br />
;lockRoom (roomID, lockIfTrue)<br />
<br />
:Locks a given room id from future speed walks (thus the mapper will never path through that room).<br />
: See also: [[#roomLocked | roomLocked()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockRoom(1, true) -- locks a room if from being walked through when speedwalking.<br />
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.<br />
</syntaxhighlight><br />
<br />
==lockSpecialExit==<br />
;lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)<br />
<br />
:Locks a given special exit, leading from one specific room to another that uses a certain command from future speed walks (thus the mapper will never path through that special exit).<br />
: See also: [[#hasSpecialExitLock | hasSpecialExitLock()]], [[#lockExit | lockExit()]], [[#lockRoom | lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2<br />
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit<br />
</syntaxhighlight><br />
<br />
==moveMapWidget==<br />
;moveMapWidget(Xpos, Ypos)<br />
:moves the map window to the given position.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
;Parameters<br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==openMapWidget==<br />
;openMapWidget([dockingArea | Xpos, Ypos, width, height])<br />
means either of these are fine:<br />
;openMapWidget()<br />
;openMapWidget(dockingArea)<br />
;openMapWidget(Xpos, Ypos, width, height)<br />
<br />
:opens a map window with given options.<br />
<br />
: See also: [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
{{note}} If no parameter is given the map window will be opened with the saved layout or at the right docking position (similar to clicking the icon)<br />
* ''dockingArea:''<br />
: If only one parameter is given this parameter will be a string that contains one of the possible docking areas the map window will be created in (f" floating "t" top "b" bottom "r" right and "l" left)<br />
{{note}} If 4 parameters are given the map window will be created in floating state <br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''width:''<br />
: The width map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height map window, in pixels. Passed as an integer number.<br />
<br />
==pauseSpeedwalk==<br />
;pauseSpeedwalk()<br />
<br />
:Pauses a speedwalk started using [[#speedwalk|speedwalk()]]<br />
<br />
: See also: [[#speedwalk|speedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = pauseSpeedwalk()<br />
if not ok then<br />
debugc(f"Error: unable to pause speedwalk because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
==registerMapInfo==<br />
;registerMapInfo(label, function)<br />
<br />
Adds an extra 'map info' to the mapper widget which can be used to display custom information.<br />
<br />
: See also: [[#killMapInfo|killMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
{{note}}<br />
You can register multiple map infos - just give them unique names and toggle whichever ones you need.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info will be registered and visible in select box under mapper. You can use it later to kill map info, enable it, disable it or overwrite using [[#registerMapInfo|registerMapInfo()]] again.<br />
* ''function:''<br />
: Callback function that will be responsible for returning information how to draw map info fragment.<br />
<br />
Callback function is called with following arguments:<br />
* ''roomId'' - current roomId or currently selected room (when multiple selection is made this is center room)<br />
* ''selectionSize'' - how many rooms are selected<br />
* ''areaId'' - roomId's areaId<br />
* ''displayedAreaId'' - areaId that is currently displayed<br />
<br />
Callback needs to return following:<br />
* ''text'' - text that will be displayed (when empty, nothing will be displayed, if you want to "reserve" line or lines use not empty value " " or add line breaks "\n")<br />
* ''isBold'' (optional) - true/false - determines whether text will be bold <br />
* ''isItalic'' (optional) - true/false - determines whether text will be italic<br />
* ''color r'' (optional) - color of text red component (0-255)<br />
* ''color g'' (optional) - color of text green component (0-255)<br />
* ''color b'' (optional) - color of text blue component (0-255)<br />
<br />
{{note}}<br />
Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.<br />
<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea) <br />
return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),<br />
true, true, 0, 255, 0<br />
end)<br />
enableMapInfo("My very own handler!")<br />
</syntaxhighlight><br />
<br />
Example will display something like that:<br />
<br />
[[File:Map-info-example.png]]<br />
<br />
Using function arguments is completely optional and you can determine whether and how to display map info completely externally.<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("Alert", function() <br />
if character.hp < 20 then<br />
return "Look out! Your HP is getting low", true, false, unpack(color_table.red) -- will display red, bolded warning whne character.hp is below 20<br />
else<br />
return "" -- will not return anything<br />
end<br />
end)<br />
enableMapInfo("Alert")<br />
</syntaxhighlight><br />
<br />
==resumeSpeedwalk==<br />
;resumeSpeedwalk()<br />
<br />
:Continues a speedwalk paused using [[#pauseSpeedwalk|pauseSpeedwalk()]]<br />
: See also: [[#speedwalk|speedwalk()]], [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = resumeSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")<br />
return<br />
end<br />
cecho("\n<green>Successfully resumed speedwalk!\n")<br />
</syntaxhighlight><br />
<br />
==removeCustomLine==<br />
;removeCustomLine(roomID, direction) <br />
<br />
:Removes the custom exit line that's associated with a specific exit of a room.<br />
:See also: [[#addCustomLine|addCustomLine()]], [[#getCustomLines|getCustomLines()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- remove custom exit line that starts in room 315 going north<br />
removeCustomLine(315, "n")<br />
</syntaxhighlight><br />
<br />
==removeMapEvent==<br />
;removeMapEvent(event name)<br />
<br />
:Removes the given menu entry from a mappers right-click menu. You can add custom ones with [[#addMapEvent | addMapEvent()]].<br />
: See also: [[#addMapEvent | addMapEvent()]], [[#getMapEvents | getMapEvents()]], [[#removeMapMenu | removeMapMenu()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- add one to the general menu<br />
removeMapEvent("room a") -- removes the said menu<br />
</syntaxhighlight><br />
<br />
==removeMapMenu==<br />
;removeMapMenu(menu name)<br />
<br />
:Removes the given submenu from a mappers right-click menu. You can add custom ones with [[#addMapMenu | addMapMenu()]].<br />
: See also: [[#addMapMenu | addMapMenu()]], [[#getMapMenus | getMapMenus()]], [[#removeMapEvent | removeMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Test") -- add submenu to the general menu<br />
removeMapMenu("Test") -- removes that same menu again<br />
</syntaxhighlight><br />
<br />
==removeSpecialExit==<br />
;removeSpecialExit(roomID, command) <br />
<br />
:Removes the special exit which is accessed by ''command'' from the room with the given ''roomID''.<br />
:See also: [[#addSpecialExit|addSpecialExit()]], [[#clearSpecialExits|clearSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2<br />
removeSpecialExit(1, "pull rope") -- removes the exit again<br />
</syntaxhighlight><br />
<br />
==resetRoomArea==<br />
;resetRoomArea (roomID)<br />
<br />
: Unassigns the room from its given area. While not assigned, its area ID will be -1. Note that since Mudlet 3.0 the "default area" which has the id of -1 may be selectable in the area selection widget on the mapper - although there is also an option to conceal this in the settings.<br />
<br />
: See also: [[#setRoomArea | setRoomArea()]], [[#getRoomArea | getRoomArea()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetRoomArea(3143)<br />
</syntaxhighlight><br />
<br />
==resizeMapWidget==<br />
;resizeMapWidget(width, height)<br />
:resizes a map window with given width, height.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
* ''width:''<br />
: The width of the map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the map window, in pixels. Passed as an integer number.<br />
<br />
==roomExists==<br />
;roomExists(roomID)<br />
<br />
:Returns a boolean true/false depending if the room with that ID exists (is created) or not.<br />
<br />
==roomLocked==<br />
;locked = roomLocked(roomID)<br />
<br />
:Returns true or false whenever a given room is locked.<br />
: See also: [[#lockRoom|lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))<br />
</syntaxhighlight><br />
<br />
==saveJsonMap==<br />
; saveJsonMap([pathFileName])<br />
Saves all the data that is normally held in the Mudlet map (''.dat'' as a binary format) in text (JSON) format. It does take longer to do this, so a progress dialog will be shown indicating the status. <br />
<br />
: See also: [[#loadJsonMap|loadJsonMap()]]<br />
{{MudletVersion|4.11.0}}<br />
<br />
; Parameters:<br />
* ''pathFileName'' (optional in Mudlet 4.12+): a string that is an absolute path and file name to save the data into.<br />
<br />
; Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
==saveMap==<br />
;saveMap([location], [version])<br />
<br />
:Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work. You can also save the map in the Mapper settings tab.<br />
<br />
;Parameters<br />
* ''location''<br />
: (optional) save the map to the given location if provided, or the default one otherwise.<br />
* ''version''<br />
: (optional) map version as a number to use when saving (Mudlet 3.17+)<br />
<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")<br />
if not savedok then<br />
echo("Couldn't save :(\n")<br />
else<br />
echo("Saved fine!\n")<br />
end<br />
<br />
-- save with a particular map version<br />
saveMap(20)<br />
</syntaxhighlight><br />
<br />
==searchAreaUserData==<br />
;searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])<br />
:Searches Areas' User Data in a manner exactly the same as [[#searchRoomUserData|searchRoomUserData()]] does in all Rooms' User Data, refer to that command for the specific details except to replace references to rooms and room ID numbers there with areas and areas ID numbers.<br />
<br />
==searchRoom== <br />
;searchRoom (room number | room name[, case-sensitive [, exact-match]])<br />
:Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of ''roomid = roomname'', the optional second and third boolean parameters have been available since Mudlet 3.0;<br />
<br />
::If no rooms are found, then an empty table is returned.<br />
<br />
:If you pass it a '''number''' instead of a '''string''' as just one argument, it'll act like [[#getRoomName|getRoomName()]] and return the room name.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- show the behavior when given a room number:<br />
display(searchRoom(3088))<br />
"The North Road South of Taren Ferry"<br />
<br />
-- show the behavior when given a string:<br />
-- shows all rooms containing the text in any case:<br />
display(searchRoom("North road"))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road",<br />
[3146] = "Bend in the North Road",<br />
[3088] = "The North Road South of Taren Ferry",<br />
[6229] = "Grassy Field By North Road"<br />
}<br />
-- or:<br />
-- display(searchRoom("North road",false))<br />
-- display(searchRoom("North road",false,false))<br />
-- would both also produce those results.<br />
<br />
-- shows all rooms containing the text in ONLY the letter-case provided:<br />
display(searchRoom("North road",true,false))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3117] = "North road",<br />
}<br />
<br />
-- shows all rooms containing ONLY that text in either letter-case:<br />
lua searchRoom("North road",false,true)<br />
{<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road"<br />
}<br />
<br />
-- shows all rooms containing only and exactly the given text:<br />
lua searchRoom("North road",true,true)<br />
{<br />
[3115] = "North road",<br />
[3117] = "North road"<br />
}<br />
</syntaxhighlight><br />
{{note}} Technically, with both options (case-sensitive and exact-match) set to true, one could just return a list of numbers as we know precisely what the string will be, but it was kept the same for maximum flexibility in user scripts.<br />
<br />
==searchRoomUserData== <br />
;searchRoomUserData([key, [value]])<br />
:A command with three variants that search though all the rooms in sequence (so '''not as fast as a user built/maintained ''index'' system''') and find/reports on the room user data stored:<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;searchRoomUserData(key, value)<br />
<br />
:Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key". <br />
<br />
;searchRoomUserData(key)<br />
<br />
:Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key". <br />
<br />
;searchRoomUserData()<br />
<br />
:Reports a (sorted) list of the unique keys from all rooms with user data with any (case sensitive) "key", available since Mudlet 3.0. It is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if I had stored the details of "named doors" as part of the room user data --<br />
display(searchRoomUserData("doorname_up"))<br />
<br />
--[[ could result in a list:<br />
{<br />
"Eastgate",<br />
"Northgate",<br />
"boulderdoor",<br />
"chamberdoor",<br />
"dirt",<br />
"floorboards",<br />
"floortrap",<br />
"grate",<br />
"irongrate",<br />
"rockwall",<br />
"tomb",<br />
"trap",<br />
"trapdoor"<br />
}]]<br />
<br />
-- then taking one of these keys --<br />
display(searchRoomUserData("doorname_up","trapdoor"))<br />
<br />
--[[ might result in a list:<br />
{<br />
3441,<br />
6113,<br />
6115,<br />
8890<br />
}<br />
]]</syntaxhighlight><br />
<br />
==setAreaName==<br />
;setAreaName(areaID or areaName, newName)<br />
<br />
:Names, or renames an existing area to the new name. The area must be created first with [[#addAreaName|addAreaName()]] and it must be unique.<br />
<br />
{{note}} parameter areaName is available since Mudlet 3.0.<br />
<br />
:See also: [[#deleteArea|deleteArea()]], [[#addAreaName|addAreaName()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setAreaName(2, "My city")<br />
<br />
-- available since Mudlet 3.0<br />
setAreaName("My old city name", "My new city name")<br />
</syntaxhighlight><br />
<br />
==setAreaUserData==<br />
;setAreaUserData(areaID, key (as a string), value (as a string))<br />
<br />
:Stores information about an area under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. Returns a lua ''true'' value on success. You can have as many keys as you'd like, however a blank key will not be accepted and will produce a lua ''nil'' and an error message instead.<br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#getAreaUserData|getAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store extra area details...<br />
setAreaUserData(34, "country", "Andor.")<br />
<br />
-- or a sound file to play in the background (with a script that checks a room's area when entered)...<br />
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))<br />
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)<br />
</syntaxhighlight><br />
<br />
==setCustomEnvColor==<br />
;setCustomEnvColor(environmentID, r,g,b,a)<br />
<br />
:Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.<br />
: See also: [[#getCustomEnvColorTable|getCustomEnvColorTable()]], [[#setRoomEnv|setRoomEnv()]]<br />
<br />
{{note}} Numbers 1-16 and 257-272 are reserved by Mudlet. 257-272 are the default colors the user can adjust in mapper settings, so feel free to use them if you'd like - but don't overwrite them with this function.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200<br />
local r,g,b = unpack(color_table.blue)<br />
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue<br />
</syntaxhighlight><br />
<br />
==setDoor==<br />
;setDoor(roomID, exitCommand, doorStatus)<br />
<br />
:Creates or deletes a door in a room. Doors are purely visual - they don't affect pathfinding. You can use the information to adjust your speedwalking path based on the door information in a room, though.<br />
<br />
:Doors CAN be set on stub exits ''- so that map makers can note if there is an obvious door to somewhere even if they do not (yet) know where it goes, perhaps because they do not yet have the key to open it!''<br />
<br />
:Returns ''true'' if the change could be made, ''false'' if the input was valid but ineffective (door status was not changed), and ''nil'' with a message string on invalid input (value type errors).<br />
<br />
: See also: [[#getDoors|getDoors()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to create the door in.<br />
* ''exitCommand:''<br />
: The cardinal direction for the door is in - it can be one of the following: '''n''', '''e''', '''s''', '''w''', '''ne''', '''se''', '''sw''', '''ne'''. ''{Plans are afoot to add support for doors on the other normal exits: '''up''', '''down''', '''in''' and '''out''', and also on special exits - though more work will be needed for them to be shown in the mapper.}'' It is important to ONLY use these direction codes as others e.g. "UP" will be accepted - because a special exit could have ANY name/lua script - but it will not be associated with the particular normal exit - recent map auditing code about to go into the code base will REMOVE door and other room exit items for which the appropriate exit (or stub) itself is not present, so in this case, in the absence of a special exit called "UP" that example door will not persist and not show on the normal "up" exit when that is possible later on.<br />
<br />
* ''doorStatus:''<br />
: The door status as a number - '''0''' means no (or remove) door, '''1''' means open door (will draw a green square on exit), '''2''' means closed door (yellow square) and '''3''' means locked door (red square). <br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a door on the east exit of room 4234 that is currently open<br />
setDoor(4234, 'e', 1)<br />
<br />
-- remove a door from room 923 that points north<br />
setDoor(923, 'n', 0)<br />
</syntaxhighlight><br />
<br />
==setExit==<br />
;setExit(from roomID, to roomID, direction)<br />
<br />
:Creates a one-way exit from one room to another using a standard direction - which can be either one of ''n, ne, nw, e, w, s, se, sw, u, d, in, out'', the long version of a direction, or a number which represents a direction. If there was an exit stub in that direction already, then it will be automatically deleted for you.<br />
<br />
:Returns ''false'' if the exit creation didn't work.<br />
<br />
: See also: [[#addSpecialExit|addSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^exit (\d+) (\d+) (\w+)$<br />
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north<br />
<br />
if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then<br />
echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))<br />
else<br />
echo("Failed to set the exit.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
This function can also delete exits from a room if you use it like so:<br />
<br />
<syntaxhighlight lang="lua">setExit(from roomID, -1, direction)</syntaxhighlight><br />
<br />
- which will delete an outgoing exit in the specified direction from a room.<br />
<br />
==setExitStub==<br />
;setExitStub(roomID, direction, set/unset)<br />
<br />
Creates or removes an exit stub from a room in a given directions. You can use exit stubs later on to connect rooms that you're sure of are together. Exit stubs are also shown visually on the map, so the mapper can easily tell which rooms need finishing.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room to place an exit stub in, as a number.<br />
* ''direction:''<br />
: The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.<br />
* ''set/unset:''<br />
: A boolean to create or delete the exit stub.<br />
<br />
: See also: [[#getExitStubs|getExitStubs()]], [[#connectExitStub|connectExitStub()]]<br />
<br />
;Example<br />
Create an exit stub to the south from room 8:<br />
<syntaxhighlight lang="lua"><br />
setExitStub(8, "s", true)<br />
</syntaxhighlight><br />
<br />
How to delete all exit stubs in a room:<br />
<syntaxhighlight lang="lua"><br />
for i,v in pairs(getExitStubs(roomID)) do<br />
setExitStub(roomID, v,false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setExitWeight==<br />
;setExitWeight(roomID, exitCommand, weight)<br />
<br />
:Gives an exit a weight, which makes it less likely to be chosen for pathfinding. All exits have a weight of 0 by default, which you can increase. Exit weights are set one-way on an exit - if you'd like the weight to be applied both ways, set it from the reverse room and direction as well.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set the weight in.<br />
* ''exitCommand:''<br />
: The direction for the exit is in - it can be one of the following: '''n''', '''ne''', '''e''', '''se''', '''s''', '''sw''', '''w''', '''nw''', '''up''', '''down''', '''in''', '''out''', or, if it's a special exit, the special exit command - note that the strings for normal exits are case-sensitive and must currently be exactly as given here.<br />
* ''weight:''<br />
: Exit weight - by default, all exits have a weight of 0 meaning that the weight of the ''destination room'' is use when the route finding code is considering whether to use that exit; setting a value for an exit can increase or decrease the chance of that exit/destination room being used for a route by the route-finding code. For example, if the destination room has very high weight compared to it's neighbors but the exit has a low value then that exit and thus the room is more likely to be used than if the exit was not weighted.<br />
<br />
: See also: [[#getExitWeights|getExitWeights()]]<br />
<br />
==setGridMode==<br />
;setGridMode(areaID, true/false)<br />
<br />
:Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode; for the 2D map the custom exit lines will also not be shown if this mode is enabled. <br />
:Returns true if the area exists, otherwise false.<br />
:[[File:Mapper-regular-mode.png|none|thumb|640x640px|regular mode]][[File:Mapper-grid-mode.png|none|thumb|631x631px|grid mode]]<br />
<br />
: See also: [[#getGridMode|getGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
</syntaxhighlight><br />
<br />
==setMapUserData==<br />
;setMapUserData(key (as a string), value (as a string))<br />
<br />
:Stores information about the map under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearMapUserData|clearMapUserData()]], [[#clearMapUserDataItem|clearMapUserDataItem()]], [[#getAllMapUserData|getAllMapUserData()]], [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- store general meta information about the map...<br />
setMapUserData("game_name", "Achaea Mudlet map")<br />
<br />
-- or who the author was<br />
setMapUserData("author", "Bob")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))<br />
display("Available game info in the map: ")<br />
display(yajl.to_value(getMapUserData("some table")))<br />
</syntaxhighlight><br />
<br />
==setMapZoom==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''4.17.0''''' to allow the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet permanently remembering (it is saved within the map file) the zoom level last used for each area and with the addition of the ''getMapZoom()'' function.<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapZoom|getMapZoom()]].<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
:(Optional and only since '''Mudlet ''4.17.0''''') Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''4.17.0''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is 3.0 and the initial value - and what prior Mudlet versions started each session with - is 20.0.<br />
<br />
==setRoomArea==<br />
;setRoomArea(roomID, newAreaID or newAreaName)<br />
<br />
:Assigns the given room to a new or different area. If the area is displayed in the mapper this will have the room be visually moved into the area as well.<br />
<br />
: See also: [[#resetRoomArea|resetRoomArea()]]<br />
<br />
==setRoomChar==<br />
;setRoomChar(roomID, character)<br />
<br />
:Originally designed for an area in grid mode, takes a single ASCII character and draws it on the rectangular background of the room in the 2D map. In versions prior to Mudlet 3.8, the symbol can be cleared by using "_" as the character. In Mudlet version 3.8 and higher, the symbol may be cleared with either a space <code>" "</code> or an empty string <code>""</code>.<br />
<br />
;Game-related symbols for your map<br />
* [https://github.com/toddfast/game-icons-net-font toddfast's font] - 3000+ scalable vector RPG icons from [https://game-icons.net game-icons.net], as well as a script to download the latest icons and generate a new font.<br />
* Pixel Kitchen's [https://www.fontspace.com/donjonikons-font-f30607 Donjonikon Font] - 10x10 fantasy and RPG-related icons.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomChar(431, "#")<br />
<br />
setRoomChar(123, "$")<br />
<br />
-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings<br />
setRoomChar(666, "👿")<br />
</syntaxhighlight><br />
<br />
:'''Since Mudlet version 3.8 :''' this facility has been extended:<br />
:* This function will now take a short string of any printable characters as a room ''symbol'', and they will be shrunk to fit them all in horizontally but if they become too small that ''symbol'' may not be shown if the zoom is such that the room symbol is too small to be legible.<br />
:* As "_" is now a valid character an existing symbol may be erased with either a space " " or an empty string "" although neither may be effective in some previous versions of Mudlet.<br />
:* Should the rooms be set to be drawn as circles this is now accommodated and the symbol will be resized to fit the reduce drawing area this will cause.<br />
:* The range of characters that are available are now dependent on the '''fonts''' present in the system and a setting on the "Mapper" tab in the preferences that control whether a specific font is to be used for all symbols (which is best if a font is included as part of a game server package, but has the issue that it may not be displayable if the user does not have that font or chooses a different one) or any font in the user's system may be used (which is the default, but may not display the ''glyph'' {the particular representation of a ''grapheme'' in a particular font} that the original map creator expected). Should it not be possible to display the wanted symbol in the map because one or more of the required glyphs are not available in either the specified or any font depending on the setting then the ''replacement character'' (Unicode ''code-point'' U+FFFD '�') will be shown instead. To allow such missing symbols to be handled the "Mapper" tab on the preferences dialogue has an option to display:<br />
::* an indicator to show whether the symbol can be made just from the selected font (green tick), from the fonts available in the system (yellow warning triangle) or not at all (red cross)<br />
::* all the symbols used on the map and how they will be displayed both only using the selected font and all fonts<br />
::* the sequence of code-points used to create the symbol which will be useful when used in conjunction with character selection utilities such as ''charmap.exe'' on Windows and ''gucharmap'' on unix-like system<br />
::* a count of the rooms using the particular symbol<br />
::* a list, limited in entries of the first rooms using that symbol<br />
:* The font that is chosen to be used as the primary (or only) one for the room symbols is stored in the Mudlet map data so that setting will be included if a binary map is shared to other Mudlet users or profiles on the same system.<br />
<br />
: See also: [[#getRoomChar|getRoomChar()]]<br />
<br />
==setRoomCharColor==<br />
;setRoomCharColor(roomId, r, g, b)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set char color to.<br />
* ''r:''<br />
: Red component of room char color (0-255)<br />
* ''g:''<br />
: Green component of room char color (0-255)<br />
* ''b:''<br />
: Blue component of room char color (0-255)<br />
<br />
Sets color for room symbol.<br />
<br />
<syntaxhighlight lang="lua"><br />
setRoomCharColor(2402, 255, 0, 0)<br />
setRoomCharColor(2403, 0, 255, 0)<br />
setRoomCharColor(2404, 0, 0, 255)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
: See also: [[#unsetRoomCharColor|unsetRoomCharColor()]]<br />
<br />
==setRoomCoordinates==<br />
;setRoomCoordinates(roomID, x, y, z)<br />
<br />
:Sets the given room ID to be at the following coordinates visually on the map, where ''z'' is the up/down level. These coordinates are define the location of the room within a particular area (so not globally on the overall map).<br />
<br />
{{note}} 0,0,0 is the center of the map.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$<br />
-- this sets the current room to the supplied coordinates<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
:You can make them relative asa well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^src (\w+)$<br />
<br />
local x,y,z = getRoomCoordinates(previousRoomID)<br />
local dir = matches[2]<br />
<br />
if dir == "n" then<br />
y = y+1<br />
elseif dir == "ne" then<br />
y = y+1<br />
x = x+1<br />
elseif dir == "e" then<br />
x = x+1<br />
elseif dir == "se" then<br />
y = y-1<br />
x = x+1<br />
elseif dir == "s" then<br />
y = y-1<br />
elseif dir == "sw" then<br />
y = y-1<br />
x = x-1<br />
elseif dir == "w" then<br />
x = x-1<br />
elseif dir == "nw" then<br />
y = y+1<br />
x = x-1<br />
elseif dir == "u" or dir == "up" then<br />
z = z+1<br />
elseif dir == "down" then<br />
z = z-1<br />
end<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
==setRoomEnv==<br />
;setRoomEnv(roomID, newEnvID)<br />
<br />
:Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34<br />
</syntaxhighlight><br />
<br />
==setRoomIDbyHash==<br />
;setRoomIDbyHash(roomID, hash)<br />
<br />
:Sets the hash to be associated with the given roomID. See also [[#getRoomIDbyHash|getRoomIDbyHash()]].<br />
<br />
:If the room was associated with a different hash, or vice versa, that association will be superseded.<br />
<br />
==setRoomName==<br />
;setRoomName(roomID, newName)<br />
<br />
:Renames an existing room to a new name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomName(534, "That evil room I shouldn't visit again.")<br />
lockRoom(534, true) -- and lock it just to be safe<br />
</syntaxhighlight><br />
<br />
==setRoomUserData==<br />
;setRoomUserData(roomID, key (as a string), value (as a string))<br />
<br />
:Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store room descriptions...<br />
setRoomUserData(341, "description", "This is a plain-looking room.")<br />
<br />
-- or whenever it's outdoors or not...<br />
setRoomUserData(341, "outdoors", "true")<br />
<br />
-- how how many times we visited that room<br />
local visited = getRoomUserData(341, "visitcount")<br />
visited = (tonumber(visited) or 0) + 1<br />
setRoomUserData(341, "visitcount", tostring(visited))<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))<br />
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)<br />
</syntaxhighlight><br />
<br />
==setRoomWeight==<br />
;setRoomWeight(roomID, weight)<br />
<br />
:Sets a weight to the given roomID. By default, all rooms have a weight of 1 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.<br />
<br />
{{note}} The minimum allowed room weight is 1. <br />
<br />
:To completely avoid a room, make use of [[#lockRoom|lockRoom()]].<br />
<br />
: See also: [[#getRoomWeight|getRoomWeight()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it<br />
</syntaxhighlight><br />
<br />
<br />
==speedwalk==<br />
;speedwalk(dirString, backwards, delay, show)<br />
<br />
:A speedwalking function will work on cardinal+ordinal directions (n, ne, e, etc.) as well as u (for up), d (for down), in and out. It can be called to execute all directions directly after each other, without delay, or with a custom delay, depending on how fast your game allows you to walk. It can also be called with a switch to make the function reverse the whole path and lead you backwards.<br />
<br />
:Call the function by doing: <code>speedwalk("YourDirectionsString", true/false, delaytime, true/false)</code><br />
<br />
:The delaytime parameter will set a delay between each move (set it to 0.5 if you want the script to move every half second, for instance). It is optional: If you don't indicate it, the script will send all direction commands right after each other. (If you want to indicate a delay, you -have- to explicitly indicate true or false for the reverse flag.)<br />
<br />
:The show parameter will determine if the commands sent by this function are shown or hidden. It is optional: If you don't give a value, the script will show all commands sent. (If you want to use this option, you -have- to explicitly indicate true or false for the reverse flag, as well as either some number for the delay or nil if you do not want a delay.)<br />
<br />
:The "YourDirectionsString" contains your list of directions and steps (e.g.: "2n, 3w, u, 5ne"). Numbers indicate the number of steps you want it to walk in the direction specified after it. The directions must be separated by anything other than a letter that can appear in a direction itself. (I.e. you can separate with a comma, spaces, the letter x, etc. and any such combinations, but you cannot separate by the letter "e", or write two directions right next to each other with nothing in-between, such as "wn". If you write a number before every direction, you don't need any further separator. E.g. it's perfectly acceptable to write "3w1ne2e".) The function is not case-sensitive.<br />
<br />
:If your game only has cardinal directions (n,e,s,w and possibly u,d) and you wish to be able to write directions right next to each other like "enu2s3wdu", you'll have to change the pattern slightly. Likewise, if your game has any other directions than n, ne, e, se, s, sw, w, nw, u, d, in, out, the function must be adapted to that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
speedwalk("16d1se1u")<br />
-- Will walk 16 times down, once southeast, once up. All in immediate succession.<br />
<br />
speedwalk("2ne,3e,2n,e")<br />
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.<br />
<br />
speedwalk("IN N 3W 2U W", false, 0.5)<br />
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.<br />
<br />
speedwalk("5sw - 3s - 2n - w", true)<br />
-- Will walk backwards: east, twice south, thrice north, five times northeast. All in immediate succession.<br />
<br />
speedwalk("3w, 2ne, w, u", true, 1.25)<br />
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.<br />
</syntaxhighlight><br />
<br />
{{note}} The probably most logical usage of this would be to put it in an alias. For example, have the pattern ''^/(.+)$'' execute: <code>speedwalk(matches[2], false, 0.7)</code><br />
And have ''^//(.+)$'' execute: <code>speedwalk(matches[2], true, 0.7)</code><br />
Or make aliases like: ''^banktohome$'' to execute <syntaxhighlight lang="lua" inline>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight><br />
<br />
{{note}} The show parameter for this function is available in Mudlet 3.12+<br />
<br />
==stopSpeedwalk==<br />
;stopSpeedwalk()<br />
<br />
:Stops a speedwalk started using [[#speedwalk|speedwalk()]]<br />
: See also: [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]], [[#speedwalk|speedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = stopSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> {err}")<br />
return<br />
end<br />
cecho(f"\n<green>Success:<reset> speedwalk stopped")<br />
</syntaxhighlight><br />
<br />
==unHighlightRoom==<br />
;unHighlightRoom(roomID)<br />
<br />
:Unhighlights a room if it was previously highlighted and restores the rooms original environment color.<br />
: See also: [[#highlightRoom|highlightRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
unHighlightRoom(4534)<br />
</syntaxhighlight><br />
<br />
==unsetRoomCharColor==<br />
;unsetRoomCharColor(roomId)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to unset char color to.<br />
<br />
Removes char color setting from room, back to automatic determination based on room background lightness.<br />
<br />
<syntaxhighlight lang="lua"><br />
unsetRoomCharColor(2031)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==updateMap==<br />
;updateMap()<br />
<br />
:Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.<br />
<br />
: See also: [[#centerview|centerview()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete a some room<br />
deleteRoom(500)<br />
-- now make the map show that it's gone<br />
updateMap()<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Release_Checklist&diff=20721Release Checklist2024-01-08T17:52:40Z<p>Vadi: </p>
<hr />
<div>= Mudlet release checklist =<br />
# 5 days before the release (14 if it's a long one)<br />
## ☐ announce start of testing in Discord channel #mudlet-testing with the list of additions/improvements/fixes (but not infrastructure), and add link to latest download builds (from [https://make.mudlet.org/snapshots Latest Branch Snapshots], but double check that sha matches [https://github.com/Mudlet/Mudlet/commits/development the latest commit]).<br />
## ☐ [automated] update <code>mudlet.ts</code> with the latest translations strings for translators to translate<br />
## ☐ [automated] update <code>mudlet_en_US.ts</code> with the latest translation strings, translate/update the few plural forms it contains as necessary and then generate the binary translation <code>mudlet_en_US.qm</code> file and merge it into the repo (see [https://wiki.mudlet.org/w/Translating_Mudlet#English_.28American.29_translation Translating Mudlet - English (American) translation]).<br />
## ☐ merge outstanding approved pull requests<br />
## ☐ create a new <code>release-<version></code> branch off <code>development</code><br />
## ☐ go through every single commit (in main repo and installers) and ensure all new functionality is documented<br />
## ☐ [automated] update [http://www.mudlet.org/geyser/files/index.html Geyser docs]<br />
## ☐ [automated] update built-in packages and scripts (IRE mapping script, ...)<br />
## ☐ [automated] update edbee to latest in our fork, and the subsequent submodule<br />
## ☐ update Patreon supporters in About tab<br />
## ☐ check all [https://github.com/Mudlet/Mudlet/issues?q=is%3Aissue+is%3Aopen+label%3Aregression regressions] to see if any must be fixed before the release<br />
## ☐ get testers to sign off (via Discord reaction) that they tested the release and it is fine with them<br />
### if a tester doesn't sign off for 2 releases, notify them, if they don't do it on the next one, remove them from the testers team<br />
## ☐ go through every single commit and write up a newspost with the latest highlights<br />
# on release day<br />
## ☐ create a new release in the 'release' channel in [https://www.dblsqd.com/user/apps/30a30c47-b1cd-48fe-b93e-ab9041b88323 dblsqd]. Make sure to enter the changelog right away, as it cannot be edited after. Include the full version number and a link to the release post ([[Media:Creating a new Mudlet release.png|example]]). A [https://www.npmjs.com/package/dblsqd-cli command-line variant] of this is: <code>dblsqd release -a mudlet -c release -m "<message>. <a href="https://mudlet.org/4-##">See the changelog</a>." <version, ie 4.11.0></code><br />
## ☐ merge latest translations from Crowdin<br />
## ☐ merge all Area 51 functions into main wiki<br />
## ☐ [https://wiki.mudlet.org/w/Manual:Lua_Functions?action=purge purge] Lua_Functions cache to ensure the latest functions are visible<br />
## ☐ merge [[Update_lua_function_list|latest autocomplete json]]<br />
## ☐ update mudlet.pro and CMakeLists.txt to new version and strip out BUILD to be empty in release branch (release process starts here)<br />
## ☐ tag in git<br />
## ☐ manually create source code package [https://github.com/Mudlet/Mudlet/blob/33ad832253d6b6411d7c1132e68455742157d60d/CI/travis.linux.after_success.sh#L144 following this]<br />
## ☐ reset BUILD in release branch to be -dev<br />
## ☐ wait for the builds to complete...<br />
## ☐ manually upload artifacts to https://www.mudlet.org/wp-content/files/?C=M;O=D through webmin. Linux and macOS ones will be available as artifacts on the Github job, while Windows is an artifact on the Appveyor job.<br />
## ☐ manually link uploaded artifacts to dblsqd[1]:<br />
## ☐ test that all binaries launch and work<br />
## ☐ create the next milestone in github<br />
## ☐ update [https://github.com/Mudlet/Mudlet/blob/development/.github/repo-metadata.yml repo-metadata.yml] to the next release version<br />
## ☐ close current github milestone<br />
## ☐ [[Howto:Update Downloads|update downloads on mudlet.org]]<br />
## ☐ [automated] create changelog with [https://github.com/Mudlet/Mudlet/actions/workflows/generate-changelog.yml a github action]<br />
## ☐ create a proper github release<br />
## ☐ [automated] insert list of translators into the post ([https://www.mudlet.org/thank-translators/crowdin.php tool])<br />
## ☐ [automated] insert list of coders into the post ([https://github.com/Mudlet/Mudlet/actions/workflows/generate-coder-attribution.yml tool])<br />
## ☐ publish release post, it will be automatically posted to mudlet.org on save<br />
## ☐ delay rest of announcements until 3-4 days past the release; post when there are no verified issues in update<br />
## ☐ post to #announcements in Discord. Publish the post, then add a follow-up @everyone tag. This will notify folks in the Mudlet server without showing the @everyone tag in all other syncronised servers<br />
## ☐ post news to https://launchpad.net/mudlet<br />
## ☐ post thread on forums.mudlet.org<br />
## ☐ post update on achaea, starmourn, imperian, lusternia, pkuxkx.net, [http://linux.softpedia.com/get/GAMES-ENTERTAINMENT/MUD/Mudlet-45973.shtml softpedia]<br />
## ☐ post update on twitter, reddit, http://arkadia.rpg.pl, muder.ru<br />
## ☐ email to releaseradar@github.com about the update<br />
## ☐ submit mudlet windows installer to avg and avast whitelisting<br />
## ☐ merge <code>development</code> into <code>master</code> branch<br />
## ☐ update Linux distro maintainers, [https://chocolatey.org/packages/mudlet/ContactOwners Chocolatey maintainer], flag package outdated on arch (release process ends here)<br />
## ☐ merge, don't squash or rebase, the release branch into development (but don't delete right away, keep it around for a potential hotfix if needed. Delete after the next release is done). Do it right away so next day's PTB's versions is the new release.<br />
## ☐ [https://www.mudlet.org/2021/10/trial-pay-out-to-popular-prs/ create polls] for most popular changes<br />
<br />
<br />
[1]:<br />
<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach linux:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-linux-x64.AppImage.tar"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach mac:x86_64 "https://www.mudlet.org/wp-content/files/Mudlet-<release>.dmg"<br />
dblsqd push -a mudlet -c release -r "<release>" -s mudlet --type "standalone" --attach win:x86 "https://www.mudlet.org/wp-content/files/Mudlet-<release>-windows-installer.exe"<br />
<br />
<br />
= Individual contributor TODOs =<br />
* keneanung: https://github.com/users/keneanung/projects/1<br />
* vadi2: https://gist.github.com/vadi2/c4dd137010c1b969c011293eddfcee73<br />
<br />
[[Category: Mudlet Admin Manual]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Area_51&diff=20714Area 512024-01-05T14:33:01Z<p>Vadi: mention what is on and off by default</p>
<hr />
<div>{{TOC right}}<br />
<br />
This page is for the development of documentation for Lua API functions that are currently being worked on. Ideally the entries here can be created in the same format as will be eventually used in [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
which would refer to a link within the ''current'' (in this case '''Area 51''') section. Note that this ought to be removed once the article is moved to the main wiki area!<br />
<br />
The following headings reflect those present in the main Wiki area of the Lua API functions. It is suggested that new entries are added so as to maintain a sorted alphabetical order under the appropriate heading.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''onlyUseThisFont'' - a boolean indicating whether glyphs from just the ''fontName'' font are to be used or if there is not a ''glyph'' for the required ''grapheme'' (''character'') then a ''glyph'' from the most suitable different font will be substituted instead. Should this be ''true'' and the specified font does not have the required glyph then the replacement character (typically something like ''�'') could be used instead. Note that this may not affect the use of Color Emoji glyphs that are automatically used in some OSes but that behavior does vary across the range of operating systems that Mudlet can be run on.<br />
:* ''scalingFactor'' - a floating point number between 0.50 and 2.00 which modifies the size of the symbols somewhat though the extremes are likely to be unsatisfactory because some of the particular symbols may be too small (and be less visible at smaller zoom levels) or too large (and be clipped by the edges of the room rectangle or circle).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::As the symbol font details are stored in the (binary) map file rather than the profile then this function will not work until a map is loaded (or initialized, by activating a map window).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|moveRoom()]] function does for rooms and their custom exit lines. When moving a label to given coordinates this is the position that the top-left corner of the label will be positioned at; since the space allocated to a particular room on the map is ± 0.5 around the integer value of its x and y coordinates this means for a label which has a size of 1.0 x 1,0 (w x h) to position it centrally in the space for a single room at the coordinates (x, y, z) it should be positioned at (x - 0.5, y + 0.5, z).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: Label ID as number (which will be 0 or greater) or the LabelText on a text label. All labels will have a unique ID number but there may be more than one ''text'' labels with a non-empty text string; only the first matching one will be moved by this function and image labels also have no text and will match the empty string. with mo or AreaName as string containing the map label.<br />
<br />
* ''coordX/deltaX:''<br />
: A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (Optional) A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Z-axis, if omitted the label is not moved in the z-axis at all.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (Optional) a boolean value (defaults to ''false'' if omitted) as to whether to move the label to the absolute coordinates (''true'') or to move it the relative amount from its current location (''false'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- move the first label in the area with the ID number of 2, one space to the west, note the final boolean argument is unneeded<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- move the second label in the area with the ID number of 2, three and a half spaces to the west, and two south **of the center of the current level it is on in the map**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- move the (top-left corner of the first) label with the text "Home" in the area with ID number 5 to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a room within an area, in the same manner as the "move to" context menu item for one or more rooms in the 2D mapper. Like that method this will also shift the entirety of any custom exit lines defined for the room concerned. This contrasts with the behavior of the [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]] which only moves the starting point of such custom exit lines so that they still emerge from the room to which they belong but otherwise remain pointing to the original place.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (Optional) the absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Z-axis, if omitted the room is not moved in the z-axis at all.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (Optional) a boolean value (defaults to ''false'' if omitted) as to whether to move the room to the absolute coordinates (''true'') or the relative amount from its current location (''false'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- move the first room three spaces to the west, and two south **of the center of the current level it is on in the map**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - a Lua boolean ''true'' to require Mudlet to use graphemes (''character'') '''only''' from the selected font. Should a requested grapheme not be included in the selected font then the font replacement character (�) might be used instead; note that under some circumstances it is possible that the OS (or Mudlet) provided color Emoji Font may still be used but that cannot be guaranteed across all OS platforms that Mudlet might be run on;<br />
:* - a Lua boolean ''false'' to allow Mudlet to get a different ''glyph'' for a particular ''grapheme'' from the most suitable other font found in the system should there not be a ''glyph'' for it in the requested font. This is the default unless previously changed by this function or by the corresponding checkbox in the Profile Preferences dialogue for the profile concerned;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''scalingFactor'' (optional): a floating point value in the range ''0.5'' to ''2.0'' (default ''1.0'') that can be used to tweak the rectangular space that each different room symbol is scaled to fit inside; this might be useful should the range of characters used to make the room symbols be consistently under- or over-sized.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure. As the symbol font details are stored in the (binary) map file rather than the profile then this function will not work until a map is loaded (or initialised, by activating a map window).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==playMusicFile, PR #7026==<br />
;playMusicFile(settings table)<br />
:Plays music files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;"| No<br />
| finish<br />
| <msec><br />
| <br />
| style="text-align:left;"|<br />
* End play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| continue <br />
| true or false<br />
| true<br />
| style="text-align:left;" |<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{Note}} on Windows and certain files are not playing? Try installing the 3rd party [https://codecguide.com/download_k-lite_codec_pack_standard.htm K-lite codec pack].<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 20000<br />
, fadeout = 53000<br />
, start = 10000<br />
, finish = 110000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "rugby"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,finish]) ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
"C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, nil -- volume<br />
, 20000 -- fadein<br />
, 53000 -- fadeout<br />
, 10000 -- start<br />
, nil -- loops<br />
, "rugby" -- key <br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
, 110000 -- finish<br />
)<br />
</syntaxhighlight><br />
<br />
==playSoundFile, PR #7026==<br />
;playSoundFile(settings table)<br />
:Plays sound files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;"| No<br />
| finish<br />
| <msec><br />
| <br />
| style="text-align:left;"|<br />
* Finish play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{Note}} on Windows and certain files are not playing? Try installing the 3rd party [https://codecguide.com/download_k-lite_codec_pack_standard.htm K-lite codec pack].<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile({<br />
name = "cow.wav"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = getMudletHomeDir().. "/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = "C:/Users/Tamarindo/Documents/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile({<br />
name = "cow.wav"<br />
, volume = 75<br />
, fadein = nil -- nil lines are optional, no need to use<br />
, fadeout = nil -- nil lines are optional, no need to use<br />
, start = nil -- nil lines are optional, no need to use<br />
, finish = nil -- nil lines are optional, no need to use<br />
, loops = 2<br />
, key = "cow"<br />
, tag = "animals"<br />
, priority = 25<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url][,finish]) ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile(<br />
"cow.wav" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
getMudletHomeDir().. "/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
"C:/Users/Tamarindo/Documents/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile(<br />
"cow.wav" -- name<br />
, 75 -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, 2 -- loops<br />
, "cow" -- key <br />
, "animals" -- tag<br />
, 25 -- priority<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
, nil -- finish<br />
)<br />
</syntaxhighlight><br />
<br />
==stopMusic, PR #7026==<br />
;stopMusic(settings table)<br />
:Stop all music (no filter), or music that meets a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
!Default<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
|<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
|<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeaway<br />
| true or false<br />
|false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in playMusicFile().<br />
* If fadeout was not specified in playMusicFile(), then the optional fadeout parameter from stopMusic() or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeout<br />
| <br />
|5000<br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in playMusicFile().<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "rugby" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all playing music files for this profile associated with the API<br />
stopMusic({<br />
fadeaway = true<br />
})<br />
<br />
-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playMusicFile()) and then stop all playing music files for this profile associated with the API<br />
stopMusic({<br />
fadeaway = true<br />
, fadeout = 10000<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all the unique "rugby" music for this profile associated with the API<br />
stopMusic({<br />
key = "rugby"<br />
, fadeaway = true<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag][,fadeaway][,fadeout]) ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
)<br />
<br />
-- Decrease the volume for 10 seconds then stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
, true -- fadeaway<br />
, 10000 -- fadeout<br />
)<br />
</syntaxhighlight><br />
<br />
==stopSounds, PR #7026==<br />
;stopSounds(settings table)<br />
:Stop all sounds (no filter), or sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| <br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| <br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| <br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
| <br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a matching or lower priority.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeaway<br />
| true or false<br />
|false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in playSoundFile().<br />
* If fadeout was not specified in playSoundFile(), then the optional fadeout parameter from stopSounds() or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeout<br />
| <br />
|5000<br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in playSoundFile().<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds({name = "cow.wav"})<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = nil -- nil lines are optional, no need to use<br />
, tag = "animals"<br />
, priority = 50<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all playing sound files for this profile associated with the API<br />
stopSounds({<br />
fadeaway = true<br />
})<br />
<br />
-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playSoundFile()) and then stop all playing music files for this profile associated with the API<br />
stopSounds({<br />
fadeaway = true<br />
, fadeout = 10000<br />
})<br />
<br />
-- Decrease volume for 3 seconds and then stop all the tagged "animals" music for this profile associated with the API<br />
stopSounds({<br />
tag = "animals"<br />
, fadeaway = true<br />
, fadeout = 3000<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority][,fadeaway][,fadeout]) ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds("cow.wav")<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, "animals" -- tag<br />
, 50 -- priority<br />
)<br />
<br />
-- Decrease the volume for 7 seconds and then stop playing sounds<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, nil -- tag<br />
, nil -- priority<br />
, true -- fadeaway<br />
, 7000 -- fadeout<br />
)<br />
</syntaxhighlight><br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
:Creates a miniconsole window for the video player to render in, the with the given dimensions. One can only create one video player at a time (currently), and it is not currently possible to have a label on or under the video player - otherwise, clicks won't register.<br />
<br />
{{note}} A video player may also be created through use of the [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]], the [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] API command, or adding a Geyser.VideoPlayer object to ones user interface such as the example below.<br />
<br />
{{Note}} The Main Toolbar will show a '''Video''' button to hide/show the video player, which is located in a userwindow generated through createVideoPlayer, embedded in a user interface, or a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Video''' button will toggle between showing and hiding the map whether it was created using the ''createVideo'' function or as a dock-able widget.<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous Functions#loadVideoFile|loadVideoFile()]], [[Manual:Miscellaneous Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous Functions#playVideoFile|playVideoFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous Functions#playVideoFile|playVideoFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous Functions#loadVideoFile|loadVideoFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- Play a video file from the Internet, storing it in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media) so you don't need to download it over and over. You could add ", stream = false" below, but that is the default and is not needed.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [stream] download once from the Internet if the video does not exist in the profile's media directory when false (true streams from the Internet and will not download to the device) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file from the Internet, storing it in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media) so you don't need to download it over and over.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [stream] download once from the Internet if the video does not exist in the profile's media directory when false (true streams from the Internet and will not download to the device) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadVideoFile|loadVideoFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
Returns the Id number of the custom login text setting from the profile's preferences. Returns ''0'' if the option is disabled or a number greater than that for the item in the table; note it is possible if using an old saved profile in the future that the number might be higher than expected. As a design policy decision it is not permitted for a script to change the setting, this function is intended to allow a script or package to check that the setting is what it expects.<br />
<br />
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined ''doLogin()'' function, a replacement for which is shown below.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
Sends the name entered into the "Character name" field on the Connection Preferences form directly to the game server. Returns ''true'' unless there is nothing set in that entry in which case a ''nil'' and an error message will be returned instead.<br />
<br />
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined ''doLogin()'' function that may be replaced for more sophisticated requirements.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
Sends the password entered into the "Password" field on the Connection Preferences form directly to the game server. Returns ''true'' unless there is nothing set in that entry or it is too long after (or before) a connection was successfully made in which case a ''nil'' and an error message will be returned instead.<br />
<br />
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined ''doLogin()'' function, reproduced below, that may be replaced for more sophisticated requirements.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
Sends the custom login text (which does NOT depend on the user's choice of GUI language) selected in the preferences for this profile. The {password} (and {character name} if present) fields will be replaced with the values entered into the "Password" and "Character name" fields on the Connection Preferences form and then sent directly to the game server. Returns ''true'' unless there is nothing set in either of those entries (though only if required for the character name) or it is too long after (or before) a connection was successfully made or if the custom login feature is disabled, in which case a ''nil'' and an error message will be returned instead.<br />
<br />
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined ''doLogin()'' function, a replacement for which is shown below.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlet's scripting objects - triggers, aliases, and so forth.<br />
<br />
==ancestors, new in PR #6726==<br />
;ancestors(IDnumber, type)<br />
:You can use this function to find out about all the ancestors of something.<br />
<br />
:Returns a list as a table with the details of each successively distance ancestor (if any) of the given item; the details are in the form of a sub-table, within each containing specifically:<br />
:* its IDnumber as a number<br />
:* its name as a string<br />
:* whether it is active as a boolean<br />
:* its "node" (type) as a string, one of "item", "group" (folder) or "package" (module)<br />
:Returns ''nil'' and an error message if either parameter is not valid<br />
<br />
;Parameters<br />
* ''IDnumber:''<br />
: The ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button', 'trigger', 'timer', 'keybind', or 'script'.<br />
<br />
: See also: [[#isAncestorsActive|isAncestorsActive(...)]], [[#isActive|isActive(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- To do<br />
</syntaxhighlight><br />
<br />
==findItems, new in PR #6742==<br />
;findItems("name", "type"[, exact[, case sensitive]])<br />
: You can use this function to determine the ID number or numbers of items of a particular type with a given name.<br />
<br />
:Returns a list as a table with ids of each Mudlet item that matched or ''nil'' and an error message should an incorrect type string be given.<br />
<br />
;Parameters<br />
* ''name:''<br />
:The name (as a string) of the item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type (as a string) can be 'alias', 'button', 'trigger', 'timer', 'keybind' , or 'script'.<br />
* ''exact:''<br />
:(Optional) a boolean which if omitted or ''true'' specifies to match the given name against the whole of the names for items or only as a sub-string of them. As a side effect, if this is provided and is ''false'' and an empty string (i.e. ''""'') is given as the first argument then the function will return the ID numbers of ''all'' items (both temporary and permanent) of the given type in existence at the time.<br />
* ''case sensitive:''<br />
:(Optional) a boolean which if omitted or ''true'' specifies to match in a case-sensitive manner the given name against the names for items.<br />
<br />
;Example<br />
Given a profile with just the default packages installed (automatically) - including the '''echo''' one:<br />
[[File:View of standard aliases with focus on echo package.png|border|none|400px|link=]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Should find just the package with the name:<br />
lua findItems("echo", "alias")<br />
{ 3 }<br />
<br />
-- Should find both the package and the alias - as the latter contains "echo" with another character<br />
lua findItems("echo", "alias", false)<br />
{ 3, 4 }<br />
<br />
-- Finds the ID numbers of all the aliases:<br />
lua findItems("", "alias", false)<br />
{ 1, 2, 3, 4, 5, 6, 7 }<br />
<br />
-- Will still find the package with the name "echo" as we are not concerned with the casing now:<br />
lua findItems("Echo", "alias", true, false)<br />
{ 3 }<br />
<br />
-- Won't find the package with the name "echo" now as we are concerned with the casing:<br />
lua findItems("Echo", "alias", true, true)<br />
{}<br />
</syntaxhighlight><br />
<br />
==isActive, modified by PR #6726==<br />
;isActive(name/IDnumber, type[, checkAncestors])<br />
:You can use this function to check if something, or somethings, are active. <br />
<br />
:Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
:The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type can be 'alias', 'button' (from '''Mudlet 4.10'''), 'trigger', 'timer', 'keybind' (from '''Mudlet 3.2'''), or 'script' (from '''Mudlet 3.17''').<br />
* ''checkAncestors:''<br />
:(Optional) If provided AND ''true'' (considered ''false'' if absent to reproduce behavior of previous versions of Mudlet) then this function will only count an item as active if it '''and''' all its parents (ancestors) are active (from '''Mudlet tbd''').<br />
<br />
:See also: [[#exists|exists(...)]], [[#isAncestorsActive|isAncestorsActive(...)]], [[#ancestors|ancestors(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!")<br />
<br />
-- Can also be used to check if a specific item is enabled or not.<br />
if isActive("spellname", "trigger") > 0 then<br />
-- the spellname trigger is active<br />
else<br />
-- it is not active<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}} A positive ID number that does not exist will still return a ''0'' value, this is for constancy with the way the function behaves for a name that does not refer to any item either. If necessary the existence of an item should be confirmed with [[#exists|exists(...)]] first.<br />
<br />
==isAncestorsActive, new in PR #6726==<br />
;isAncestorsActive(IDnumber, "type")<br />
:You can use this function to check if '''all''' the ancestors of something are active independent of whether it itself is, (for that use the two argument form of [[#isActive|isActive(...)]]). <br />
<br />
:Returns ''true'' if all (if any) of the ancestors of the item with the specified ID number and type are active, if there are no such parents then it will also returns ''true''; otherwise returns ''false''. In the event that an invalid type string or item number is provided returns ''nil'' and an error message.<br />
<br />
;Parameters<br />
* ''IDnumber:''<br />
:The ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type can be 'alias', 'button', 'trigger', 'timer', 'keybind' or 'script' to define which item type is to be checked.<br />
<br />
:See also: [[#exists|exists(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- To do<br />
</syntaxhighlight><br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
==sendSocket revised in PR #7066 (Open)==<br />
<br />
;sendSocket(data)<br />
<br />
:Sends given binary data as-is (or with some predefined special tokens converted to byte values) to the game. You can use this to implement support for a [[Manual:Supported_Protocols#Adding_support_for_a_telnet_protocol|new telnet protocol]], [http://forums.mudlet.org/viewtopic.php?f=5&t=2272 simultronics] [http://forums.mudlet.org/viewtopic.php?f=5&t=2213#p9810 login] etc.<br />
<br />
; success = sendSocket("data")<br />
<br />
;See also: [[Manual:Lua_Functions#feedTelnet|feedTelnet()]], [[Manual:Lua_Functions#feedTriggers|feedTriggers()]]<br />
<br />
{{note}} Modified in Mudlet '''tbd''' to accept some tokens like "''<NUL>''" to include byte values that are not possible to insert with the standard Lua string escape "''\###''" form where ### is a three digit number between 000 and 255 inclusive or where the value is more easily provided via a mnemonic. For the table of the tokens that are known about, see the one in [[Manual:Lua_Functions#feedTelnet|feedTelnet()]].<br />
<br />
{{note}} The data (as bytes) once the tokens have been converted to their byte values is sent as is to the Game Server; any encoding to, say, a UTF-8 representation or to duplicate ''0xff'' byte values so they are not considered to be Telnet ''<IAC>'' (Interpret As Command) bytes must be done to the data prior to calling this function.<br />
<br />
;Parameters<br />
* ''data:''<br />
: String containing the bytes to send to the Game Server possibly containing some tokens that are to be converted to bytes as well.<br />
<br />
;Returns <br />
* (Only since Mudlet '''tbd''') Boolean ''true'' if the whole data string (after token replacement) was sent to the Server, ''false'' if that failed for any reason (including if the Server has not been connected or is now disconnected). ''nil'' and an error message for any other defect.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Tell the Server that we are now willing and able to process to process Ask the Server to a comment explaining what is going on, if there is multiple functionalities (or optional parameters) the examples should start simple and progress in complexity if needed!<br />
-- the examples should be small, but self-contained so new users can copy & paste immediately without going diving in lots other function examples first.<br />
-- comments up top should introduce / explain what it does<br />
<br />
local something = function(exampleValue)<br />
if something then<br />
-- do something with something (assuming there is a meaningful return value)<br />
end<br />
<br />
-- maybe another example for the optional second case<br />
local somethingElse = function(exampleValue, anotherValue)<br />
<br />
-- lastly, include an example with error handling to give an idea of good practice<br />
local ok, err = function()<br />
if not ok then<br />
debugc(f"Error: unable to do <particular thing> because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
-- This function is still being written up.<br />
<br />
==feedTelnet added in PR #7066 (Open)====<br />
<br />
; feedTelnet(data)<br />
<br />
:Sends given binary data with some predefined special tokens converted to byte values, to the internal telnet engine, as if it had been received from the game. This is primarily to enable testing when new Telnet sub-options/protocols are being developed. The data has to be injected into the system nearer to the point where the Game Server's data starts out than ''feedTriggers()'' and unlike the latter the data is not subject to any encoding so as to match the current profile's setting (which normally happens with ''feedTriggers()''). Furthermore - to prevent this function from putting the telnet engine into a state which could damage the processing of real game data it will refuse to work unless the Profile is completely disconnected from the game server.<br />
<br />
;See also: [[Manual:Lua_Functions#feedTriggers|feedTriggers()]], [[Manual:Lua_Functions#sendSocket|sendSocket()]]<br />
<br />
{{MudletVersion|tbd}}<br />
<br />
{{note}} This is not really intended for end-user's but might be useful in some circumstances.<br />
<br />
;Parameters<br />
* ''data''<br />
: String containing the bytes to send to the internal telnet engine as if it had come from the Game Server, it can containing some tokens listed below that are to be converted to bytes as well.<br />
<br />
;Returns <br />
* Boolean ''true'' if the ''data'' string was sent to the internal telnet engine. ''nil'' and an error message otherwise, specifically the case when there is some traces of a connection or a complete connection to the socket that passes the data to and from the game server. Additionally, if the data is an empty string ''""'' a second return value will be provided as an integer number representing a version for the table of tokens - which will be incremented each time a change is made to that table so that which tokens are valid can be determined. Note that unrecognised tokens should be passed through as is and not get replaced.<br />
<br />
{| class="wikitable sortable"<br />
|+ Token value table<br />
|-<br />
! Token !! Byte !! Version!! Notes<br />
|-<br />
|| <00> || \0x00 || 1 || 0 dec.<br />
|-<br />
|| <O_BINARY> || \0x00 || 1 || Telnet option: Binary<br />
|-<br />
|| <NUL> || \0x00 || 1 || ASCII control character: NULL<br />
|-<br />
|| <01> || \x01 || 1 || 1 dec.<br />
|-<br />
|| <O_ECHO> || \x01 || 1 || Telnet option: Echo<br />
|-<br />
|| <SOH> || \x01 || 1 || ASCII control character: Start of Heading<br />
|-<br />
|| <02> || \x02 || 1 || 2 dec. Telnet option: Reconnect<br />
|-<br />
|| <STX> || \x02 || 1 || ASCII control character: Start of Text<br />
|-<br />
|| <03> || \x03 || 1 || 3 dec.<br />
|-<br />
|| <O_SGA> || \x03 || 1 || Telnet option: Suppress Go Ahead<br />
|-<br />
|| <ETX> || \x03 || 1 || ASCII control character: End of Text<br />
|-<br />
|| <04> || \x04 || 1 || Telnet option: Approx Message Size Negotiation<br />
|-<br />
|| <EOT> || \x04 || 1 || ASCII control character: End of Transmission<br />
|-<br />
|| <05> || \x05 || 1 || <br />
|-<br />
|| <O_STATUS> || \x05 || 1 ||<br />
|-<br />
|| <ENQ> || \x05 || 1 || ASCII control character: Enquiry<br />
|-<br />
|| <06> || \x06 || 1 || Telnet option: Timing Mark<br />
|-<br />
|| <ACK> || \x06 || 1 || ASCII control character: Acknowledge<br />
|-<br />
|| <07> || \x07 || 1 || Telnet option: Remote Controlled Trans and Echo<br />
|-<br />
|| <BELL> || \x07 || 1 || ASCII control character: Bell<br />
|-<br />
|| <08> || \x08 || 1 || Telnet option: Output Line Width<br />
|-<br />
|| <BS> || \x08 || 1 ||<br />
|-<br />
|| <09> || \x09 || 1 || Telnet option: Output Page Size<br />
|-<br />
|| <HTAB> || \x09 || 1 || ASCII control character: Horizontal Tab<br />
|-<br />
|| <0A> || \x0a || 1 || Telnet option: Output Carriage-Return Disposition<br />
|-<br />
|| <LF> || \x0a || 1 || ASCII control character: Line-Feed<br />
|-<br />
|| <0B> || \x0b || 1 || Telnet option: Output Horizontal Tab Stops<br />
|-<br />
|| <VTAB> || \x0b || 1 || ASCII control character: Vertical Tab<br />
|-<br />
|| <0C> || \x0c || 1 || Telnet option: Output Horizontal Tab Disposition<br />
|-<br />
|| <FF> || \x0c || 1 || ASCII control character: Form-Feed<br />
|-<br />
|| <0D> || \x0d || 1 || Telnet option: Output Form-feed Disposition<br />
|-<br />
|| <CR> || \x0d || 1 || ASCII control character: Carriage-Return<br />
|-<br />
|| <0E> || \x0e || 1 || Telnet option: Output Vertical Tab Stops<br />
|-<br />
|| <SO> || \x0e || 1 || ASCII control character: Shift-Out<br />
|-<br />
|| <0F> || \x0f || 1 || Telnet option: Output Vertical Tab Disposition<br />
|-<br />
|| <SI> || \x0f || 1 || ASCII control character: Shift-In<br />
|-<br />
|| <10> || \x10 || 1 || Telnet option: Output Linefeed Disposition<br />
|-<br />
|| <DLE> || \x10 || 1 || ASCII control character: Data Link Escape<br />
|-<br />
|| <11> || \x11 || 1 || Telnet option: Extended ASCII<br />
|-<br />
|| <DC1> || \x11 || 1 || ASCII control character: Device Control 1<br />
|-<br />
|| <12> || \x12 || 1 || Telnet option: Logout<br />
|-<br />
|| <DC2" || \x12 || 1 || ASCII control character: Device Control 2<br />
|-<br />
|| <13> || \x13 || 1 || Telnet option: Byte Macro<br />
|-<br />
|| <DC3> || \x13 || 1 || ASCII control character: Device Control 3<br />
|-<br />
|| <14> || \x14 || 1 || Telnet option: Data Entry Terminal<br />
|-<br />
|| <DC4> || \x14 || 1 || ASCII control character: Device Control 4<br />
|-<br />
|| <15> || \x15 || 1 || Telnet option: SUPDUP<br />
|-<br />
|| <NAK> || \x15 || 1 || ASCII control character: Negative Acknowledge<br />
|-<br />
|| <16> || \x16 || 1 || Telnet option: SUPDUP Output<br />
|-<br />
|| <SYN> || \x16 || 1 || ASCII control character: Synchronous Idle<br />
|-<br />
|| <17> || \x17 || 1 || Telnet option: Send location<br />
|-<br />
|| <ETB> || \x17 || 1 || ASCII control character: End of Transmission Block<br />
|-<br />
|| <18> || \x18 || 1 ||<br />
|-<br />
|| <O_TERM> || \x18 || 1 || Telnet option: Terminal Type<br />
|-<br />
|| <CAN> || \x18 || 1 || ASCII control character: Cancel<br />
|-<br />
|| <19> || \x19 || 1 ||<br />
|-<br />
|| <O_EOR> || \x19 || 1 || Telnet option: End-of-Record<br />
|-<br />
|| <nowiki><EM></nowiki> || \x19 || 1 || ASCII control character: End of Medium<br />
|-<br />
|| <1A> || \x1a || 1 || Telnet option: TACACS User Identification<br />
|-<br />
|| <nowiki><SUB></nowiki> || \x1a || 1 || ASCII control character: Substitute<br />
|-<br />
|| <1B> || \x1b || 1 || Telnet option: Output Marking<br />
|-<br />
|| <ESC> || \x1b || 1 || ASCII control character: Escape<br />
|-<br />
|| <1C> || \x1c || 1 || Telnet option: Terminal Location Number<br />
|-<br />
|| <FS> || \x1c || 1 || ASCII control character: File Separator<br />
|-<br />
|| <1D> || \x1d || 1 || Telnet option: Telnet 3270 Regime<br />
|-<br />
|| <GS> || \x1d || 1 || ASCII control character: Group Separator<br />
|-<br />
|| <1E> || \x1e || 1 || Telnet option: X.3 PAD<br />
|-<br />
|| <RS> || \x1e || 1 || ASCII control character: Record Separator<br />
|-<br />
|| <1F> || \x1f || 1 ||<br />
|-<br />
|| <O_NAWS> || \x1f || 1 || Telnet option: Negotiate About Window Size<br />
|-<br />
|| <US> || \x1f || 1 || ASCII control character: Unit Separator<br />
|-<br />
|| <SP> || \x20 || 1 || 32 dec. ASCII character: Space<br />
|-<br />
|| <O_NENV> || \x27 || 1 || 39 dec. Telnet option: New Environment (also MNES)<br />
|-<br />
|| <O_CHARS> || \x2a || 1 || 42 dec. Telnet option: Character Set<br />
|-<br />
|| <O_KERMIT> || \x2f || 1 || 47 dec. Telnet option: Kermit<br />
|-<br />
|| <O_MSDP> || \x45 || 1 || 69 dec. Telnet option: Mud Server Data Protocol<br />
|-<br />
|| <O_MSSP> || \x46 || 1 || 70 dec. Telnet option: Mud Server Status Protocol<br />
|-<br />
|| <O_MCCP> || \x55 || 1 || 85 dec<br />
|-<br />
|| <O_MCCP2> || \x56 || 1 || 86 dec<br />
|-<br />
|| <O_MSP> || \x5a || 1 || 90 dec. Telnet option: Mud Sound Protocol<br />
|-<br />
|| <O_MXP> || \x5b || 1 || 91 dec. Telnet option: Mud eXtension Protocol<br />
|-<br />
|| <O_ZENITH> || \x5d || 1 || 93 dec. Telnet option: Zenith Mud Protocol<br />
|-<br />
|| <O_AARDWULF> || \x66 || 1 || 102 dec. Telnet option: Aardwuld Data Protocol<br />
|-<br />
|| <nowiki><DEL></nowiki> || \x7f || 1 || 127 dec. ASCII control character: Delete<br />
|-<br />
|| <O_ATCP> || \xc8 || 1 || 200 dec<br />
|-<br />
|| <O_GMCP> || \xc9 || 1 || 201 dec<br />
|-<br />
|| <T_EOR> || \xef || 1 || 239 dec<br />
|-<br />
|| <F0> || \xf0 || 1 ||<br />
|-<br />
|| <T_SE> || \xf0 || 1 ||<br />
|-<br />
|| <F1> || \xf1 || 1 ||<br />
|-<br />
|| <T_NOP> || \xf1 || 1 ||<br />
|-<br />
|| <F2> || \xf2 || 1 ||<br />
|-<br />
|| <T_DM> || \xf2 || 1 ||<br />
|-<br />
|| <F3> || \xf3 || 1 ||<br />
|-<br />
|| <T_BRK> || \xf3 || 1 ||<br />
|-<br />
|| <F4> || \xf4 || 1 ||<br />
|-<br />
|| <T_IP> || \xf4 || 1 ||<br />
|-<br />
|| <F5> || \xf5 || 1 ||<br />
|-<br />
|| <T_ABOP> || \xf5 || 1 ||<br />
|-<br />
|| <F6> || \xf6 || 1 ||<br />
|-<br />
|| <T_AYT> || \xf6 || 1 ||<br />
|-<br />
|| <F7> || \xf7 || 1 ||<br />
|-<br />
|| <T_EC> || \xf7 || 1 ||<br />
|-<br />
|| <F8> || \xf8 || 1 ||<br />
|-<br />
|| <T_EL> || \xf8 || 1 ||<br />
|-<br />
|| <F9> || \xf9 || 1 ||<br />
|-<br />
|| <T_GA> || \xf9 || 1 ||<br />
|-<br />
|| <FA> || \xfa || 1 ||<br />
|-<br />
|| <T_SB> || \xfa || 1 ||<br />
|-<br />
|| <FB> || \xfb || 1 ||<br />
|-<br />
|| <T_WILL> || \xfb || 1 ||<br />
|-<br />
|| <FC> || \xfc || 1 ||<br />
|-<br />
|| <T_WONT> || \xfc || 1 ||<br />
|-<br />
|| <FD> || \xfd || 1 ||<br />
|-<br />
|| <T_DO> || \xfd || 1 ||<br />
|-<br />
|| <FE> || \xfe || 1 ||<br />
|-<br />
|| <T_DONT> || \xfe || 1 ||<br />
|-<br />
|| <FF> || \xff || 1 ||<br />
|-<br />
|| <T_IAC> || \xff'<br />
|}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- a comment explaining what is going on, if there is multiple functionalities (or optional parameters) the examples should start simple and progress in complexity if needed!<br />
-- the examples should be small, but self-contained so new users can copy & paste immediately without going diving in lots other function examples first.<br />
-- comments up top should introduce / explain what it does<br />
<br />
local something = feedTelnet(exampleValue)<br />
if something then<br />
-- do something with something (assuming there is a meaningful return value)<br />
end<br />
<br />
-- maybe another example for the optional second case<br />
local somethingElse = function(exampleValue, anotherValue)<br />
<br />
-- lastly, include an example with error handling to give an idea of good practice<br />
local ok, err = function()<br />
if not ok then<br />
debugc(f"Error: unable to do <particular thing> because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
-- This function is still being written up.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
:These functions are used to manipulate tables. Through them you can add to tables, remove values, check if a value is present in the table, check the size of a table, and more.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
:These functions are used to construct custom user GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.<br />
<br />
==cecho2decho PR#6849 merged==<br />
; convertedString = cecho2decho(str)<br />
<br />
:Converts a cecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
decho(cecho2decho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2hecho PR#6849 merged==<br />
; convertedString = cecho2hecho(str)<br />
<br />
:Converts a cecho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2cecho|hecho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
hecho(cecho2hecho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2html PR#6849 merged==<br />
; convertedString = cecho2html(str[, resetFormat])<br />
<br />
:Converts a cecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#decho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the cecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = cecho2html(cechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==decho2cecho PR#6849 merged==<br />
; convertedString = decho2cecho(str)<br />
<br />
:Converts a decho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use cecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
cecho(decho2cecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2hecho PR#6849 merged==<br />
; convertedString = decho2hecho(str)<br />
<br />
:Converts a decho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2decho|hecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
hecho(decho2hecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2html PR#6849 merged==<br />
; convertedString = decho2html(str[, resetFormat])<br />
<br />
:Converts a decho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the decho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = decho2html(dechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==deleteMultiline PR #6779 merged==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you do not want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==echoPopup, revised in PR #6946==<br />
;echoPopup([windowName,] text, {commands}, {hints}[, useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like echo. The added text, upon being left-clicked, will do the first command in the list. Upon being right-clicked, it'll display a menu with all possible commands. The menu will be populated with hints, one for each line; if there is one extra hint then the first one will be used as a (maybe containing Qt rich-text markup) tool-tip for the text otherwise the remaining hints will be concatenated, one-per-line, as a tool-tip when the text is hovered over by the pointer.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window as a string to echo to. Use either ''main'' or omit for the main window, or the miniconsole's or user-window's name otherwise.<br />
* ''text:''<br />
: the text string to display.<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown on the right-click menu and as a tool-tip for the ''text''. If the number is the same as that of the ''commands'' table then they all will be used for the right-click menu and listed (one per line) as a plain text tooltip; alternatively if there is one extra in number than the ''commands'' table the first will be used purely for the tool tip and the remainder will be used for the right-click menu. This additional entry may be formatted as Qt style "rich-text" (in the same manner as labels elsewhere in the GUI).<br />
::* If a particular position in the ''commands'' table is an empty string ''""'' but there is something in the ''hints'' table then it will be listed in the right-click menu but as it does not do anything it will be shown ''greyed-out'' i.e. disabled and will not be clickable.<br />
::* If a particular position in '''both''' the ''commands'' and the ''hints'' table are empty strings ''""'' then this item will show as a ''separator'' (usually as a horizontal-line) in the right-click menu and it will not be clickable/do anything. <br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (color, underline, italic and other effects) if ''true'' or the link default (blue underline) if ''false'', if omitted the default format is used.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':<br />
echoPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
echoPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
<br />
-- one can also provide helpful information<br />
<br />
-- todo: an example with rich-text in the tool-tips(s) - not complete yet!<br />
echoPopup("Fancy popup", {[[echo("Doing command 1 (default one)")]], "", "", [[echo("Doing command 3")]], [[echo("Doing another command (number 4)"]], [[echo("Doing another command (number 5)"]])}, {"<p>This tooltip has HTML type tags in/around it, and it will get word-wrapped automatically to fit into a reasonable rectangle.</p><p><b>Plus</b> it can have those HTML like <i>effects</i> and be easily formatted into more than one paragraph and with <span style=\"color:cyan\">bits</span> in <span style=\"color:lime\">different</span> colors!</p><p>This example also demonstrates how to produce disabled menu (right-click) items, how to insert separators and how it now will handle multiple items with the same hint (prior to PR 6945 such duplicates will all run the command associated with the last one!) If the first command/function is an empty string then clicking on the text will have no effect, but hovering the mouse over the text will still produce the tooltip, this could be useful to display extra information about the text without doing anything by default.</p>", "Command 1 (default)", "", "Command 2 (disabled)", "Command 3", "Another command", "Another command"}, true)<br />
echo(" remaining text.\n")<br />
<br />
</syntaxhighlight><br />
<br />
==hecho2cecho PR#6849 merged==<br />
; convertedString = hecho2cecho(str)<br />
<br />
:Converts a hecho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a hecho string and use cecho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
cecho(hecho2cecho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2decho PR#6849 merged==<br />
; convertedString = hecho2decho(str)<br />
<br />
:Converts a hecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2hecho|decho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
decho(hecho2decho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2html PR#6849 merged==<br />
; convertedString = hecho2html(str[, resetFormat])<br />
<br />
:Converts a hecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2hecho|cecho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to hecho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the hecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = hecho2html(hechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==insertPopup, revised in PR #6925==<br />
;insertPopup([windowName], text, {commands}, {hints}[{, tool-tips}][, useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like echo. The added text, upon being left-clicked, will do the first command in the list. Upon being right-clicked, it'll display a menu with all possible commands. The menu will be populated with hints, one for each line; if a tool-tips table is not provided the same hints will also be listed one-per-line as a tool-tip but if a matching number of tool-tips are provided they will be concatenated to provide a tool-tip when the text is hovered over by the pointer - these tool-tips can be ''rich-text'' to produce information formatted with additional content in the same manner as labels.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window as a string to echo to. Use either ''main'' or omit for the main window, or the miniconsole's or user-window's name otherwise.<br />
* ''text:''<br />
: the text string to display.<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown on the right-click menu (and popup if no {tool-tips} table is provided). If a particular position in both the commands and hints table are both the empty string ''""'' but there is something in the tool-tips table, no entry for that position will be made in the context menu but the tool-tip can still display something which can include images or text.<br />
* ''{tool-tips}:''<br />
: (optional) a table of possibly ''rich-text'' strings which will be shown on the popup if provided. <br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (color, underline, italic and other effects) if ''true'' or the link default (blue underline) if ''false'', if omitted the default format is used.<br />
<br />
{{note}} Mudlet will distinguish between the optional tool-tips and the flag to switch between the standard link and the current text format by examining the type of the argument, as such this pair of arguments can be in either order.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':<br />
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
<br />
-- one can also provide helpful information<br />
<br />
-- todo: an example with rich-text in the tool-tips(s)<br />
<br />
</syntaxhighlight><br />
<br />
=Discord Functions=<br />
:All functions to customize the information Mudlet displays in Discord's rich presence interface. For an overview on how all of these functions tie in together, see our [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Mud Client Media Protocol=<br />
:All GMCP functions to send sound and music events. For an overview on how all of these functions tie in together, see our [[Special:MyLanguage/Manual:Scripting#MUD_Client_Media_Protocol|MUD Client Media Protocol scripting overview]].<br />
<br />
==Playing Media, PR #7026==<br />
<br />
===Playing Media===<br />
<br />
Send '''Client.Media.Play''' GMCP events to play sound or music files.<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| "name"<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| "url"<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely and a url was not set above with Client.Media.Default or Client.Media.Load.<br />
|-<br />
| style="text-align:center;"| No<br />
| "type"<br />
| "sound" or "music"<br />
| "sound"<br />
| style="text-align:left;"|<br />
* Identifies the type of media.<br />
|-<br />
| style="text-align:center;"| No<br />
| "tag"<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;"| No<br />
| "volume"<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadein"<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|"fadeout"<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| "start"<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
* 1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| "finish"<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* End play at the specified position in milliseconds.<br />
* 1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|"loops"<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;"|<br />
* Number of iterations that the media plays.<br />
* A value of -1 allows the sound or music to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|"priority"<br />
|1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|"continue"<br />
| true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Only valid for media files with a "type" of "music".<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|-<br />
| style="text-align:center;" |No<br />
|"key"<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
|}<br />
<br />
==== name====<br />
<br />
For example, to simply play the sound of a cow mooing already stored in the "media" folder:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
Or some lightning stored in a "weather" sub-folder under the "media" folder.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "weather/lightning.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
The "name" parameter may be used for stopping media with the Client.Media.Stop GMCP event.<br />
<br />
====url====<br />
<br />
If you maintain your sound files on the Internet and don't set a default URL with Client.Media.Default, or preload them with Client.Media.Load, include the "url" parameter:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav",<br />
"url": "https://www.example.com/sounds/"<br />
}<br />
</syntaxhighlight><br />
<br />
====type: sound====<br />
<br />
Media files default to a "type" of "sound" when the "type" parameter is not specified, such as in the example above. It is good practice to specify the "type" parameter to best keep media organized within your implementation:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav",<br />
"type": "sound"<br />
}<br />
</syntaxhighlight><br />
<br />
The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====tag====<br />
<br />
To play the sound of a sword swooshing and categorized as "combat":<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sword1.wav",<br />
"type": "sound",<br />
"tag": "combat"<br />
}<br />
</syntaxhighlight><br />
<br />
The "tag" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====type: music====<br />
<br />
Add background music to your environment through use of the "music" value set upon the "type" parameter:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "river.wav",<br />
"type": "music",<br />
"tag": "environment"<br />
}<br />
</syntaxhighlight><br />
<br />
The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====volume: 1 to 100====<br />
<br />
As the character draws nearer to or farther from the environmental feature, consider adjusting the "volume" parameter. Example values, followed by syntax examples:<br />
<br />
*Maximum: 100 (recommended to use rarely)<br />
*High: 75<br />
*Default: 50<br />
* Low: 25<br />
* Minimum: 1 (recommended to use rarely)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "river.wav",<br />
"type": "music",<br />
"tag": "environment",<br />
"volume": 75<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "volume" values of type string ("75") into integers (75) as needed.<br />
<br />
====fadein====<br />
<br />
Increase volume from the start of the media [start position, volume one] to the number in milliseconds specified with the "fadein" parameter [position start + milliseconds, volume specified with the "volume" parameter]. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (no fade in)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "monty_python.mp3",<br />
"type": "music",<br />
"volume": 100,<br />
"fadein": 1000<br />
}<br />
</syntaxhighlight><br />
+---------------------------+-----------------------+<br />
| Fade in 1000 milliseconds | Normal |<br />
+---------------------------+-----------------------+<br />
Volume 1|........::::::::::iiiiiiiii%%%%%%%%%%%%%%%%%%%%%%%%|Volume 100<br />
+---------------------------+-----------------------+<br />
Although using the integer type is recommended, Mudlet parses "fadein" values of type string ("1000") into integers (1000) as needed.<br />
<br />
==== fadeout====<br />
<br />
Decrease volume from a position in milliseconds subtracted from the duration of the media [position duration - milliseconds, volume specified with the "volume" parameter] to the end of the media [position duration, volume one]. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (no fade out)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "the_matrix.mp3",<br />
"type": "music",<br />
"volume": 50,<br />
"fadeout": 333<br />
}<br />
</syntaxhighlight><br />
+-----------------------+---------------------------+<br />
| Normal | Fade out 333 milliseconds |<br />
+-----------------------+---------------------------+<br />
Volume 50|%%%%%%%%%%%%%%%%%%%%%%%%iiiiiiiii::::::::::........|Volume 1<br />
+-----------------------+---------------------------+<br />
Although using the integer type is recommended, Mudlet parses "fadeout" values of type string ("333") into integers (333) as needed.<br />
<br />
==== start ====<br />
<br />
Start playing a media track at the number of milliseconds specified. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (start from beginning)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "mudlet_beatboxing.mp3",<br />
"type": "music",<br />
"volume": 75,<br />
"start": 1000<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "start" values of type string ("100") into integers (100) as needed.<br />
<br />
==== finish ====<br />
<br />
Finish playing a media track at the number of milliseconds specified. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (start from beginning)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "mudlet_beatboxing.mp3",<br />
"type": "music",<br />
"volume": 75,<br />
"finish": 35000<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "finish" values of type string ("100") into integers (100) as needed.<br />
<br />
==== loops: -1, 1 or more ====<br />
<br />
The "loops" parameter controls how many times the sound repeats and defaults to 1 if not specified. A value of -1 will loop the file indefinitely.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "clock/hour_bell.wav",<br />
"type": "sound",<br />
"loops": 3<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "underdark.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "loops" values of type string ("-1") into integers (-1) as needed.<br />
<br />
==== priority: 1 to 100 ====<br />
<br />
The "priority" parameter sets precedence for Client.Media.Play GMCP events that include a "priority" setting. The values for the "priority" parameter range between 1 and 100. Given that two Client.Media.Play GMCP events have the same priority, the media already playing will continue playing. In Mudlet, media without priority set is not included comparisons based on priority.<br />
<br />
A common place to find priority implemented is with combat. In the following example, imagine a combat scenario where some sounds of sword thrusts were interrupted by a successful blocking maneuver.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sword1.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"loops": 3,<br />
"priority": 60<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "block1.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"priority": 70<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "priority" values of type string ("25") into integers (25) as needed.<br />
<br />
The "priority" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====continue: true or false (for music)====<br />
<br />
Typically sent with the "type" of "music" is the parameter "continue", which presents the following values:<br />
<br />
*true: continues music that is already playing if it is requested again through a new Client.Media.Play GMCP event<br />
*false: restarts music that is already playing if it is requested again through a new Client.Media.Play GMCP event<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "city.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"continue": true<br />
}<br />
</syntaxhighlight><br />
<br />
If the "continue" parameter is not specified, behavior will default to ''true'' for music.<br />
<br />
Although using the boolean type is recommended, Mudlet parses "continue" values of type string ("true" and "false") into boolean (''true'' and ''false'') as needed, as not all game drivers support a boolean type.<br />
<br />
==== key====<br />
<br />
The "key" parameter enables media categorization, similar to the "tag" parameter, however it adds a feature of uniqueness that halts media currently playing with the same key, replacing it with the media that arrived from a new Client.Media.Play GMCP event. This update will only occur if the "name" or "url" associated with the currently playing media does not match the new media, while the key is identical.<br />
<br />
In the example below, consider that a player moves from a sewer area to a village. The "key" parameter is used to stop the previously playing ''sewer.mp3'' and start playing ''village.mp3'' within the second Client.Media.Play GMCP event. <br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sewer.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": true,<br />
"key": "area-music"<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "village.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": true,<br />
"key": "area-music"<br />
}<br />
</syntaxhighlight><br />
<br />
The "key" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
{{note}} Where music is bound to change, continue or stop as a player enters a new room, consider allowing for a slight pause of 1 heart beat or tick to send the Client.Media.Play or Client.Media.Stop GMCP events. This practice reduces the number of Client.Media.Play GMCP events sent when the player travels through several rooms quickly.<br />
<br />
==== randomization====<br />
<br />
Wildcards ''*'' (asterisk) and ''?'' (question mark) may be used within the name to randomize media file(s) selection.<br />
<br />
Given that media files underdark.wav, underdark.mp3 and underdark_dark_elven_moshpit.mp3 were all present in the media/environment directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play using the ''*'' wildcard.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "underdark*",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": false<br />
}<br />
</syntaxhighlight><br />
<br />
If media files sword1.wav, sword2.wav and sword3.wav were all present in the media/combat directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play per each loop using the ''?'' wildcard.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "combat/sword?.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"loops": 3<br />
}<br />
</syntaxhighlight><br />
<br />
==Stopping Media, PR #7026==<br />
<br />
=== Stopping Media ===<br />
<br />
Send '''Client.Media.Stop''' GMCP events to stop sound or music media.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" | No<br />
| "name"<br />
|<file name><br />
| style="text-align:left;" |<br />
*Stops playing media by name matching the value specified.<br />
|-<br />
| style="text-align:center;" | No<br />
|"type"<br />
|"sound" or "music"<br />
| style="text-align:left;" | <br />
*Stops playing media by type matching the value specified.<br />
|-<br />
| style="text-align:center;" |No<br />
| "tag"<br />
|<tag><br />
| style="text-align:left;" |<br />
*Stops playing media by tag matching the value specified.<br />
|-<br />
| style="text-align:center;" |No<br />
|"priority"<br />
|1 to 100<br />
| style="text-align:left;" |<br />
*Stops playing media with priority less than or equal to the value.<br />
|-<br />
| style="text-align:center;" |No<br />
|"key"<br />
|<key><br />
| style="text-align:left;" | <br />
*Stops playing media by key matching the value specified.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadeaway"<br />
| true or false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in Client.Media.Play.<br />
* If fadeout was not specified in Client.Media.Play, then the optional fadeout parameter from Client.Media.Stop or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadeout"<br />
| <br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in Client.Media.Play.<br />
|-<br />
|}<br />
<br />
====all====<br />
<br />
Send the Client.Media.Stop GMCP event with no parameters to stop all playing media within a given game profile.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {}<br />
</syntaxhighlight><br />
<br />
====parameters====<br />
<br />
Send any combination of the name, type, tag, priority or sound parameters and valid corresponding values to stop playing media that matches ''all'' combinations of the parameters.<br />
<br />
Stop the rain.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"name": "rain.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media using the "type" of "sound".<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"type": "sound"<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media categorized with the "tag" of "combat" ''and'' that has a "priority" less than or equal to 50.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"tag": "combat",<br />
"priority": 50<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media categorized with the "key" of "area-music".<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"key": "area-music"<br />
}<br />
</syntaxhighlight><br />
<br />
Decrease volume for 5 seconds (or the fadeout parameter defined in Client.Media.Play) and then stop all playing music files for this profile<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"fadeaway": true<br />
}<br />
</syntaxhighlight><br />
<br />
Decrease volume for 10 seconds all media categorized with the "key" of "area-music" and then stop the music<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"key": "area-music",<br />
"fadeaway": true,<br />
"fadeout": 10000<br />
}<br />
</syntaxhighlight><br />
<br />
=Supported Protocols, PR #7058=<br />
<br />
Mudlet supports CHARSET, NEW-ENVIRON, MNES, MTTS, GMCP, MSSP, MSP, ATCP, Aardwolfs 102, MSDP, and the MXP Protocol.<br />
<br />
CHARSET, NEW-ENVIRON, MTTS, MXP, MSSP, MSP, GMCP and 102 are enabled by default, MSDP and MNES can be enabled in settings.<br />
<br />
==NEW-ENVIRON, PR #7058==<br />
To enhance the player experience through sharing more client-supported details, the Telnet New-Environ Option may be used to transfer client environment variables from Mudlet to game servers. Sharing supporting information on information such as encoding, terminal emulation, and accessibility options aims to improve initial player setup and increase the retention rate for new gaming community members.<br />
<br />
===NEW-ENVIRON in Mudlet===<br />
Mudlet supports two methods of information exchange via NEW-ENVIRON, the first via [https://datatracker.ietf.org/doc/html/rfc1572 RFC 1572]: '''Telnet New-Environ Option''' (on by default), and the second is [https://tintin.mudhalla.net/protocols/mnes/ MNES]: '''Mud New-Environ Standard''' (off by default), which shares a standardized set of client information across multiple clients. <br />
<br />
====Client Environment Variable Updates====<br />
Mudlet provides a user-friendly interface for managing environmental variables through its Settings menu. For certain environmental variables, manual selections made in the Settings menus can dynamically notify servers that have expressed interest in the client's environmental variables through the negotiation of the NEW-ENVIRON option. For instance, when a Mudlet user updates the data encoding for a server profile by navigating to Settings, General, and choosing a specific data encoding from the drop-down menu, this information becomes available for transmission via both the RFC (default) and MNES (requires user enabling) options. <br />
<br />
==== Available Client Environment Variables [https://datatracker.ietf.org/doc/html/rfc1572 RFC 1572] ====<br />
Two types of variables are used per RFC 152, well-known variables defines with VAR (0) and for less common variables, USERVAR (3). Some information requires a user to OPT-IN to share it with the game. Some client variables updates may be reported ad-hoc with an INFO (2) message. If there is no value for a defined variable, a VAL (1) will be sent without a value following it.<br />
{| class="wikitable"<br />
! Type<br />
! Variable<br />
! Example Values<br />
!Mudlet Default<br />
!OPT-IN<br />
!INFO<br />
! Purpose<br />
!Available<br />
|-<br />
| VAR<br />
| '''SYSTEMTYPE'''<br />
| MACOS, WIN64, WIN32, BSD4, CYGWIN, FREEBSD, HURD, NETBSD, OPENBSD, LINUX, UNIX<br />
|<br />
|Yes<br />
|<br />
| Client runs within the listed operating system.<br />
|Future<br />
|-<br />
| VAR<br />
| '''USER'''<br />
| tamarindo<br />
|<br />
|Yes<br />
|<br />
| Character name defined in logon dialogue.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''256_COLORS'''<br />
| 1, 0<br />
|1<br />
|<br />
|<br />
| Client supports all 256 color codes. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''ANSI'''<br />
| 1, 0<br />
|1<br />
|<br />
|<br />
| Client supports all common ANSI color codes. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CHARSET'''<br />
| UTF-8, ASCII<br />
|<br />
|<br />
|Yes<br />
| Encoding set in the client<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CLIENT_NAME'''<br />
| MUDLET<br />
|MUDLET<br />
|<br />
|<br />
| Name of the client.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CLIENT_VERSION'''<br />
| 4/18, 4/17/2-DEV<br />
|<br />
|<br />
|<br />
| Version of the client.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''FONT'''<br />
| Bitstream Vera Sans Mono<br />
|<br />
|Yes<br />
|Yes<br />
| Font used in the client.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''FONT_SIZE'''<br />
| 14<br />
|<br />
|Yes<br />
|Yes<br />
| Font size used in the client.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''LANGUAGE'''<br />
| en_US<br />
|<br />
|Yes<br />
|Yes<br />
| Client is using this language code and country variant.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''MTTS'''<br />
| 2349<br />
|<br />
|<br />
|Yes<br />
| Bitvector defined in the Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]).<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''OSC_COLOR_PALETTE'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports OSC and the OSC color palette. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''SCREEN_READER'''<br />
| 1, 0<br />
|0<br />
|Yes<br />
|Yes<br />
| Client is using a screen reader. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TERMINAL_TYPE'''<br />
| ANSI-TRUECOLOR, ANSI-256COLOR, ANSI, XTERM, VT100, DUMB<br />
|ANSI-TRUECOLOR<br />
|<br />
|<br />
| Terminal type of the client<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TLS'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports Transport Layer Security for data encryption. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TRUECOLOR'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports truecolor codes using semicolon notation. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''UTF-8'''<br />
| 1, 0<br />
|<br />
|<br />
|Yes<br />
| Client is using UTF-8 character encoding. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''VT100'''<br />
| 1, 0<br />
|0<br />
|<br />
|<br />
| Client supports all common VT100 codes. 1 = Yes/True/ACK. This is not applicable for Mudlet and while defined, is not used.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''WORD_WRAP'''<br />
| 100<br />
|<br />
|<br />
|Yes<br />
| Client wraps text at this value<br />
|4.18<br />
|-<br />
|}<br />
<br />
====Negotiating NEW-ENVIRON====<br />
Negotiating the NEW-ENVIRON Telnet option empowers game servers to request one, multiple, or all client environment variables configured within Mudlet. The process unfolds with the game server sending a Telopt DO NEW-ENVIRON (39), prompting Mudlet to respond with a WILL NEW-ENVIRON (39). Subsequently, the game server can send SB NEW-ENVIRON (39) SEND to receive all available environment variables. Mudlet responds with SB NEW-ENVIRON (39) IS (0) < VAR (0) | USERVAR (3) > "<variable>" [VAL (1)] ["<value>"] [ .. [ VAR (0) | USERVAR (3) ] "<variable>" VAL (1) "<value>"] containing the list of environmental variables.<br />
<br />
Once an environmental variable is transmitted to a server within the ongoing connection, Mudlet replies with SB NEW-ENVIRON (39) INFO (2) < VAR (0) | USERVAR (3) > "<variable>" [VAL (1)] ["<value>"] messages for select variables. Importantly, no reply from the server is required in this context. If there is a need to specify a particular list of requested environmental variables to Mudlet, the format SB NEW-ENVIRON (39) SEND < VAR (0) | USERVAR (3) > "<variable>" [ .. < VAR (0) | USERVAR (3) > "<variable>" ] can be employed.<br />
<br />
Success example #1 (one environmental variable):<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND (1) USERVAR (3) ''CHARSET'' IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
|-<br />
|}<br />
<br />
Success example #2 (all environmental variables):<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND (1) IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''SYSTEMTYPE'' VAL (1) ''MACOS'' VAR (0) ''USER'' VAL (1) ''tamarindo'' USERVAR (3) ''256_COLORS'' VAL (1) ''1'' USERVAR (3) ''ANSI'' VAL (1) ''1'' USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' USERVAR (3) ''CLIENT_NAME'' VAL (1) ''MUDLET'' USERVAR (3) ''CLIENT_VERSION'' VAL (1) ''4/17/2-DEV'' USERVAR (3) ''FONT'' VAL (1) ''Bitstream Vera Sans Mono'' USERVAR (3) ''FONT_SIZE'' VAL (1) ''14'' USERVAR (3) ''LANGUAGE'' VAL (1) ''en_US'' USERVAR (3) USERVAR (3) ''MTTS'' VAL (1) ''2349'' USERVAR (3) ''OSC_COLOR_PALETTE'' VAL (1) ''1'' USERVAR (3) ''SCREEN_READER'' VAL (1) USERVAR (3) ''TERMINAL_TYPE'' VAL (1) ''ANSI-TRUECOLOR'' USERVAR (3) ''TLS'' VAL (1) ''1'' USERVAR (3) ''TRUECOLOR'' VAL (1) ''1'' USERVAR (3) ''UTF-8'' VAL (1) ''1'' USERVAR (3) ''VT100'' VAL (1) ''0'' USERVAR (3) ''WORD_WRAP'' VAL (1) ''100'' IAC SE<br />
|-<br />
|<br />
|''[ As updates occur in the client the following are possible... ]''<br />
|-<br />
|<br />
|IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''FONT'' VAL (1) ''Bitstream Vera Sans Mono'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''FONT_SIZE'' VAL (1) ''14'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''LANGUAGE'' VAL (1) ''en_US'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''MTTS'' VAL (1) ''2349'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''SCREEN_READER'' VAL (1) IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''UTF-8'' VAL (1) ''1'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''WORD_WRAP'' VAL (1) ''100'' IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to negotiate environmental variables, they may choose the Settings, Special Options menu item in Mudlet and enable "Force NEW_ENVIRON negotiation off". The following is an example of an attempted negotiation where "Force NEW-ENVIRON negotiation off" is enabled.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WONT NEW-ENVIRON (39) IAC SE<br />
|-<br />
|}<br />
<br />
NEW-ENVIRON negotiation is available in Mudlet 4.18+.<br />
<br />
== MNES, PR #7058 ==<br />
The Mud New-Environment Standard is an alternative way to share client-supported details between Mudlet to game servers.<br />
<br />
==== Activating MNES ====<br />
If your game supports MNES, instruct users to toggle on the `Enable MNES` menu option on the General tab in Mudlet.<br />
<br />
[[File:Screenshot_2024-01-01_at_1.41.06_PM.png|alt=Enable MNES is found on the Game protocols section of the General tab of Settings|614x614px]]&nbsp;<br />
<br />
==== Mud New-Environ Standard Client Environment Variables [https://tintin.mudhalla.net/protocols/mnes/ MNES] ====<br />
MNES leverages VAR (0) to transfer up to five client environment variables. Some client variables updates may be reported ad-hoc with an INFO message. If there is no value for a defined variable, a VAL (1) will be sent without a value following it.<br />
{| class="wikitable"<br />
! Type<br />
! Variable<br />
! Example Values<br />
!Mudlet Default<br />
!INFO<br />
! Purpose<br />
|-<br />
| VAR<br />
| '''CHARSET'''<br />
| UTF-8, ASCII<br />
|<br />
|Yes<br />
| Encoding set in the client<br />
|-<br />
| VAR<br />
| '''CLIENT_NAME'''<br />
| MUDLET<br />
|MUDLET<br />
|<br />
| Name of the client.<br />
|-<br />
| VAR<br />
| '''CLIENT_VERSION'''<br />
| 4/18, 4/17/2-DEV<br />
|<br />
|<br />
| Version of the client.<br />
|-<br />
| VAR<br />
| '''MTTS'''<br />
| 2349<br />
|<br />
|Yes<br />
| Bitvector defined in the Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]).<br />
|-<br />
| VAR<br />
| '''TERMINAL_TYPE'''<br />
| ANSI-TRUECOLOR, ANSI-256COLOR, ANSI, XTERM, VT100, DUMB<br />
|ANSI-TRUECOLOR<br />
|<br />
| Terminal type of the client<br />
|-<br />
|}<br />
<br />
==== Negotiating MNES ====<br />
The primary differences between MNES and the out-of-the-box RFC 152 NEW-ENVIRON implementation is that MNES sends no more than 5 client environment variables ("IPADDRESS" will not be implemented in Mudlet), it uses a VAR (0) for the SEND (1), IS (0), and INFO (2) messages, and returns a multiple client variable response in multiple IS (0) messages.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CLIENT_NAME'' VAL (1) ''MUDLET'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CLIENT_VERSION'' VAL (1) ''4/17/2-DEV'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''MTTS'' VAL (1) ''2349'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''TERMINAL_TYPE'' VAL (1) ''ANSI-TRUECOLOR'' IAC SE<br />
|-<br />
|<br />
|''[ As updates occur in the client the following are possible... ]''<br />
|-<br />
|<br />
|IAC SB NEW-ENVIRON (39) INFO (2) VAR (0) ''CHARSET'' VAL (1) ''ASCII'' IAC SE<br />
IAC SB NEW-ENVIRON (39) INFO (2) VAR (0) ''MTTS'' VAL (1) ''2345'' IAC SE<br />
|-<br />
|}<br />
<br />
MNES negotiation is available in Mudlet 4.18+.<br />
<br />
==MTTS, PR #7036==<br />
MUD servers frequently seek information about the capabilities of a MUD Client. Despite the availability of various methods, achieving consistency and reliability in this endeavor has proven challenging. The Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]) aims to alleviate these issues by introducing a transparent and straightforward standard for MUD Clients to communicate their terminal capabilities. This standard builds upon and formalizes [https://datatracker.ietf.org/doc/html/rfc1091 RFC 1091], which outlines the Telnet Terminal-Type Option.<br />
<br />
===MTTS in Mudlet===<br />
By incorporating the Mud Terminal-Type Standard (MTTS), Mudlet will communicate with interested servers that it possesses the following capabilities: <br />
<br />
* '''Support for ANSI Color Codes:''' The client supports all common ANSI color codes.<br />
* '''UTF-8 Character Encoding:''' The client utilizes UTF-8 character encoding.<br />
* '''Support for 256 Color Codes:''' Mudlet is equipped to handle all 256 color codes.<br />
* '''OSC Color Palette:''' Mudlet acknowledges support for the OSC color palette.<br />
* '''Screen Reader Support:''' Mudlet offers support for screen readers, with opt-in functionality (not advertised by default).<br />
* '''Truecolor Codes:''' Mudlet supports truecolor codes using semicolon notation.<br />
* '''Mud New Environment Standard (MNES) Support:''' The client adheres to the Mud New Environment Standard for information exchange.<br />
* '''TLS Encryption:''' The client supports Transport Layer Security for data encryption.<br />
<br />
==== Screen Reader Opt-In ====<br />
Users can find on the Accessibility tab under the Settings menu a checkbox identified as "Advertise screen reader use via protocols supporting this notice" which when checked will notify interested game servers. This information may be used to optimize the gaming experience.<br />
<br />
[[File:Screenshot_2024-01-01_at_2.35.07_PM.png|alt=Image displaying the Advertise screen reader checkbox|619x619px]]<br />
<br />
==== Available MTTS Information ====<br />
Through a Telnet TERMINAL-TYPE Option negotiation, Mudlet transfers a bitvector to game servers, (i.e., <code>2349</code>) for processing. A bitvector, also known as a bitmap, is a data structure that represents a fixed-size sequence of binary digits or bits. In a bitvector, each bit corresponds to a specific position or index in the sequence, and its value can be either 0 or 1. The MTTS bitvector represents is a set of flags and boolean values, where each bit can represent the state of a particular boolean condition or flag. For example, if the third bit is set to <code>1</code>, it indicates that the client is using UTF-8 character encoding. A <code>0</code> indicator would indicate that UTF-8 was not supported.<br />
{| class="wikitable"<br />
|+MTTS Bitvector<br />
!Bit<br />
!Property<br />
!Meaning<br />
|-<br />
|1<br />
|ANSI<br />
|Client supports all common ANSI color codes.<br />
|-<br />
|2<br />
|VT100<br />
|Client supports all common VT100 codes.<br />
|-<br />
|4<br />
|UTF-8<br />
|Client is using UTF-8 character encoding.<br />
|-<br />
|8<br />
|256 COLORS<br />
|Client supports all 256 color codes.<br />
|-<br />
|16<br />
|MOUSE TRACKING<br />
|Client supports xterm mouse tracking.<br />
|-<br />
|32<br />
|OSC COLOR PALETTE<br />
|Client supports OSC and the OSC color palette.<br />
|-<br />
|64<br />
|SCREEN READER<br />
|Client is using a screen reader.<br />
|-<br />
|128<br />
|PROXY<br />
|Client is a proxy allowing different users to connect from the same IP address.<br />
|-<br />
|256<br />
|TRUECOLOR<br />
|Client supports truecolor codes using semicolon notation.<br />
|-<br />
|512<br />
|MNES<br />
|Client supports the Mud New Environment Standard for information exchange.<br />
|-<br />
|1024<br />
|MSLP<br />
|Client supports the Mud Server Link Protocol for clickable link handling.<br />
|-<br />
|2048<br />
|TLS<br />
|Client supports Transport Layer Security for data encryption.<br />
|}<br />
<br />
====Negotiating MTTS====<br />
Per the MTTS guidance, game servers should initiate up to 4 TTYPE requests to complete the TTYPE cycling routine within a given connection. If the connection is reset, negotiate TTYPE again. Reference the [https://tintin.mudhalla.net/protocols/mtts/ MTTS website] for more information.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO TTYPE (24) IAC SE<br />
| IAC WILL TTYPE (24) IAC SE<br />
|-<br />
| IAC SB TTYPE (24) SEND (1) IAC SE<br />
| IAC SB TTYPE (24) IS (0) ''MUDLET-4/18'' IAC SE<br />
|-<br />
| IAC SB TTYPE (24) SEND (1) IAC SE<br />
| IAC SB TTYPE (24) IS (0) ''ANSI-TRUECOLOR'' IAC SE<br />
|-<br />
|IAC SB TTYPE (24) SEND (1) IAC SE<br />
|IAC SB TTYPE (24) IS (0) ''MTTS 2349'' IAC SE<br />
|-<br />
|IAC SB TTYPE (24) SEND (1) IAC SE<br />
|IAC SB TTYPE (24) IS (0) ''MTTS 2349'' IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to enable Mud Terminal Type Standard, they may choose the Settings, General menu item in Mudlet and toggle off the "Enable MTTS" checkbox.<br />
<br />
MTTS is available in Mudlet 4.18+.<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
<br />
===sysWindowOverflowEvent, PR #6872===<br />
Raised when the content in a mini-console/user window that has been set to be '''non-scrolling''' (see: [[#enableScrolling|enableScrolling(...)]] and [[#disableScrolling|disableScrolling(...)]]) overflows - i.e. fills the visible window and overflows off the bottom. Returns two additional arguments being the window's name as a string and the number of lines that have gone past that which can be shown on the current size of the window.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6872 and https://github.com/Mudlet/Mudlet/pull/6848 for the Lua API functions (that also need documenting).</div>Vadihttps://wiki.mudlet.org/index.php?title=Mobile_Plan&diff=20659Mobile Plan2023-12-26T12:25:40Z<p>Vadi: </p>
<hr />
<div>Tentative plan for making Mudlet available on Android and iOS:<br />
# Do research on similar Qt Widgets applications that have mobile versions to learn from their experience.<br />
# Identify the key business logic components and extract them out into separate classes/modules:<br />
#* Game connection and communication (handles connecting to game server, sending/receiving data)<br />
#* User input processing (handles keyboard/mouse input)<br />
#* Game display/rendering (handles displaying game text and maps)<br />
#* Scripting engine (runs Lua scripts)<br />
#* Settings/configuration<br />
# Create a "Mudlet Core" module that contains just the essential functionality needed for scripting:<br />
#* Game communication<br />
#* Input processing<br />
#* Display rendering<br />
#* Scripting engine<br />
# Implement a minimal Qt Widgets UI that uses Mudlet Core to provide a desktop authoring environment for creating/testing scripts.<br />
# Create a stripped down "Mudlet Mobile" app that links only to Mudlet Core using QML. It would provide:<br />
#* Simple UI for connecting to a MUD<br />
#* Ability to select/run scripts created on desktop<br />
#* Basic input buttons on screen<br />
#* Text display<br />
# Allow exporting scripts from desktop UI to a shared script repository.<br />
# Mobile app can download scripts from repository to run them.<br />
# Both apps share the same Mudlet Core component for running scripts.<br />
<br />
This allows creating a full-featured desktop app for authoring, while still having a lightweight mobile app that can leverage the scripts. The key is the reusable Mudlet Core module that encapsulates the scripting logic.<br />
<br />
=== Prior art ===<br />
<br />
* VLC: uses a libVLC as a core, Qt Widget for desktop and a native Kotlin interface on Android<br />
* Krita: ?</div>Vadihttps://wiki.mudlet.org/index.php?title=Mobile_Plan&diff=20658Mobile Plan2023-12-26T12:22:25Z<p>Vadi: </p>
<hr />
<div>Tentative plan for making Mudlet available on Android and iOS:<br />
# Identify the key business logic components and extract them out into separate classes/modules:<br />
#* Game connection and communication (handles connecting to game server, sending/receiving data)<br />
#* User input processing (handles keyboard/mouse input)<br />
#* Game display/rendering (handles displaying game text and maps)<br />
#* Scripting engine (runs Lua scripts)<br />
#* Settings/configuration<br />
# Create a "Mudlet Core" module that contains just the essential functionality needed for scripting:<br />
#* Game communication<br />
#* Input processing<br />
#* Display rendering<br />
#* Scripting engine<br />
# Implement a minimal Qt Widgets UI that uses Mudlet Core to provide a desktop authoring environment for creating/testing scripts.<br />
# Create a stripped down "Mudlet Mobile" app that links only to Mudlet Core using QML. It would provide:<br />
#* Simple UI for connecting to a MUD<br />
#* Ability to select/run scripts created on desktop<br />
#* Basic input buttons on screen<br />
#* Text display<br />
# Allow exporting scripts from desktop UI to a shared script repository.<br />
# Mobile app can download scripts from repository to run them.<br />
# Both apps share the same Mudlet Core component for running scripts.<br />
<br />
This allows creating a full-featured desktop app for authoring, while still having a lightweight mobile app that can leverage the scripts. The key is the reusable Mudlet Core module that encapsulates the scripting logic.</div>Vadihttps://wiki.mudlet.org/index.php?title=Mobile_Plan&diff=20657Mobile Plan2023-12-26T12:21:27Z<p>Vadi: Created page with "# Identify the key business logic components and extract them out into separate classes/modules: #* Game connection and communication (handles connecting to game server, sendi..."</p>
<hr />
<div># Identify the key business logic components and extract them out into separate classes/modules:<br />
#* Game connection and communication (handles connecting to game server, sending/receiving data)<br />
#* User input processing (handles keyboard/mouse input)<br />
#* Game display/rendering (handles displaying game text and maps)<br />
#* Scripting engine (runs Lua scripts)<br />
#* Settings/configuration<br />
# Create a "Mudlet Core" module that contains just the essential functionality needed for scripting:<br />
#* Game communication<br />
#* Input processing<br />
#* Display rendering<br />
#* Scripting engine<br />
# Implement a minimal Qt Widgets UI that uses Mudlet Core to provide a desktop authoring environment for creating/testing scripts.<br />
# Create a stripped down "Mudlet Mobile" app that links only to Mudlet Core. It would provide:<br />
#* Simple UI for connecting to a MUD<br />
#* Ability to select/run scripts created on desktop<br />
#* Basic input buttons on screen<br />
#* Text display<br />
# Allow exporting scripts from desktop UI to a shared script repository.<br />
# Mobile app can download scripts from repository to run them.<br />
# Both apps share the same Mudlet Core component for running scripts.<br />
<br />
This allows creating a full-featured desktop app for authoring, while still having a lightweight mobile app that can leverage the scripts. The key is the reusable Mudlet Core module that encapsulates the scripting logic.</div>Vadihttps://wiki.mudlet.org/index.php?title=Fonts&diff=20652Fonts2023-12-25T08:29:24Z<p>Vadi: </p>
<hr />
<div>= Fonts =<br />
<br />
A collection of open source, typically monospaced fonts recommended by Mudlet users.<br />
<br />
* [https://fontlibrary.org/en/font/neomatrixcode Neomatrix Code] - monospaced font for developers<br />
* [https://github.com/tonsky/FiraCode Fira Code] - free monospaced font with programming ligatures<br />
* [https://www.jetbrains.com/lp/mono/ JetBrains Mono/]<br />
* [https://sourcefoundry.org/hack/ Hack]<br />
* [https://en.wikipedia.org/wiki/Source_Code_Pro Source Code Pro]<br />
<br />
<br />
'''How to choose the next font you want to test?''' <br />
<br />
* Try [https://www.codingfont.com/ Coding Font], a "gamified experience to help you find your true love of coding fonts!" This is quite fun, lets you keep comparing and choosing between pairs of fonts until you get down to the one you like most.<br />
* [https://www.programmingfonts.org/ programmingfonts.org] provides a quick way to preview a lot of programming fonts.</div>Vadihttps://wiki.mudlet.org/index.php?title=Main_Page&diff=20643Main Page2023-12-24T11:39:46Z<p>Vadi: </p>
<hr />
<div><languages/><br />
<!-- BANNER ACROSS TOP OF PAGE --><br />
{| id="mp-topbanner" style="width:100%; background:#fcfcfc; margin-top:1.2em; border:1px solid #ccc;"<br />
| style="width:56%; color:#000;" |<br />
<!-- "WELCOME TO THE MUDLET WIKI" AND ARTICLE COUNT --><br />
{| style="width:280px; border:none; background:none;"<br />
| style="width:280px; text-align:center; white-space:nowrap; color:#000;" |<br />
<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#000;"><translate><!--T:1--> Welcome to the Mudlet Wiki!</translate></div><br />
|}<br />
<!-- BASIC INTRO --><br />
{| id="mp-upper" style="margin:0 0 0 0; background:none;"<br />
| class="MainPageBG" style="width:100%; border:1px solid #c9c07f; background:#c9c07f; vertical-align:top; color:#000;" |<br />
{| id="mp-left" cellpadding="2" cellspacing="5" style="width:100%; vertical-align:top; background:#fdf7bb;"<br />
! <h2 id="mp-tfa-h2" style="margin:0; background:#f4e9bc; font-size:120%; font-weight:bold; border:1px solid #a3b00f; text-align:left; color:#000; padding:0.2em 0.4em;"><translate><!--T:2--> About Mudlet</translate></h2><br />
|-<br />
| style="color:#000;" | <div id="mp-tfa"><br />
<br />
{{TOC right}}<br />
<br />
<translate><br />
<!--T:3--><br />
A cross-platform, open source, and super fast [http://en.wikipedia.org/wiki/Mud_client MUD client] with scripting in [http://en.wikipedia.org/wiki/Lua Lua].<br />
<br />
<!--T:4--><br />
New to Mudlet? Why not start with [http://mudlet.org/media the basics], or take a look at '''[[Special:MyLanguage/Manual:Contents | Mudlet Manual]]'''. Or perhaps you want to find the answer to a [[Special:MyLanguage/FAQ | Frequently Asked Question]]. If you don't have it yet, [http://www.mudlet.org/download/ download it] - it's free, and works on Windows, macOS, and Linux computers.<br />
<br />
<!--T:5--><br />
Are you having troubles with Mudlet? We can help. [http://forums.mudlet.org/viewforum.php?f=9 Start here].<br />
<br />
<br />
== External Links == <!--T:6--><br />
<br />
<!--T:7--><br />
* [http://www.mudlet.org Mudlet Homepage]<br />
* [http://forums.mudlet.org Forums]<br />
<br />
<br />
== Wiki Links == <!--T:8--><br />
<br />
<!--T:9--><br />
* [[Special:MyLanguage/Manual:Contents | Mudlet Manual]]<br />
* [[Manual:Technical_Manual|Technical Manual]]<br />
** [[Special:MyLanguage/Manual:Lua Functions | Mudlet Lua API]]<br />
*** [[Manual:Database Functions]]<br />
*** [[Manual:Date/Time Functions]]<br />
*** [[Manual:Discord Functions]]<br />
*** [[Manual:Mapper Functions]]<br />
*** [[Manual:Miscellaneous Functions]]<br />
*** [[Manual:Mudlet Object Functions]]<br />
*** [[Manual:Networking Functions]]<br />
*** [[Manual:String Functions]]<br />
*** [[Manual:Table Functions]]<br />
*** [[Manual:Text to Speech Functions]]<br />
*** [[Manual:UI Functions]]<br />
* [https://www.mudlet.org/geyser/files/geyser/Geyser.html Geyser Reference Docs]<br />
* [[Special:MyLanguage/FAQ | Frequently Asked Questions]]<br />
* [http://forums.mudlet.org/viewforum.php?f=6 Mudlet Packages Forum]<br />
* [[Special:MyLanguage/Compiling Mudlet|Compiling Mudlet]]<br />
* [[Special:MyLanguage/Translating Mudlet|Translating Mudlet]]<br />
* [[Accessibility]]<br />
<br />
== MUD standards == <!--T:10--><br />
<br />
<!--T:11--><br />
We will preserve the documentation of MUD standards that may get lost (because the original site is breaking down or is already offline) as they are implemented in Mudlet. We may also look into developing some of them in the future.<br />
* [[Special:MyLanguage/Standards:MMP | MUD Mapping Protocol]]<br />
* [[Special:MyLanguage/Standards:Discord_GMCP | Discord Rich Presence over GMCP]]<br />
* [[Special:MyLanguage/Standards:MUD_Client_Media_Protocol | Mud Client Media Protocol]]<br />
<br />
== Lua == <!--T:12--><br />
<br />
<!--T:13--><br />
Mudlet uses Lua! Learning it is really rewarding - take a look at excellent stuff like the [http://luatut.com/ Lua tutorial] (has an intro+crash course), [http://tylerneylon.com/a/learn-lua/ Learn Lua in 15 mins] (if you're familiar with coding already), [http://www.lua.org/pil/ Programming in Lua] (official, but might be hard to follow) and various [http://lua-users.org/wiki/TutorialDirectory Lua tutorials].<br />
<br />
<br />
== Special Links == <!--T:14--><br />
<br />
<!--T:15--><br />
* [[Special:AllPages | All Pages]]<br />
* [[Special:MyLanguage/Report Spam|Report spam]] if you notice suspicious behavior<br />
<br />
<br />
== Using MediaWiki == <!--T:16--><br />
<br />
<!--T:17--><br />
Interested in contributing to this site? Please do! While first edit will be manually approved (this is to help against spambots), any follow-up edits will show up right away.<br />
<br />
Use the following links to learn more about MediaWiki: (note that the following links are not related to Mudlet)<br />
<br />
<!--T:18--><br />
* [http://www.mediawiki.org/wiki/Help:Formatting Wiki syntax]<br />
* [http://en.wikipedia.org/wiki/Help:Table Wiki table syntax]<br />
<br />
</translate><br />
<br />
|}<br />
|}<br />
|}</div>Vadihttps://wiki.mudlet.org/index.php?title=Manual:Screen_Readers&diff=20458Manual:Screen Readers2023-05-30T14:30:35Z<p>Vadi: /* Quick Accessibility Configuration */ mention default shortcut</p>
<hr />
<div>{{TOC right}}<br />
=What is a screen reader=<br />
<br />
The term, "Screen reader", refers to a piece of software on a computing device that is capable of examining the screen of the device and relaying that information to someone who is blind or visually impaired through the use of synthetic speech or Braille. Screen readers exist on desktops, laptops, mobile devices, and even gaming consoles.<br />
<br />
=Screen reader agnostic tips =<br />
<br />
== Quick Accessibility Configuration ==<br />
<br />
Mudlet comes with a command that works with every new profile you create. The purpose of this command is to perform certain operations on Mudlet itself, not the MUD you're connected to.<br />
<br />
The two commands that are relevant to screen reader users are:<br />
* <code>mudlet access on</code><br />
* <code>mudlet access reader</code><br />
<br />
Typing in the first command will set a few things up that'll make the experience better for screen reader users, among which is setting <code>Ctrl+Tab</code> as the shortcut to change focus between the input line and the main window.<br />
<br />
The second command will install an optional package called [https://github.com/tspivey/mudlet-reader/ Reader] which was initially designed to improve the state of accessibility on Mac OSX, but offers some additional features for Windows and Linux as well.<br />
<br />
==Alt menus==<br />
Holding Alt to open the menubar currently does not work. As a workaround, Alt+P opens preferences and Alt+E opens the script editor.<br />
<br />
==Input line==<br />
Sent commands are selected and kept in the input line by default, which is useful for sighted users. To make it easier for screen readers, go to preferences - Input line tab - and Set the following options as indicated:<br />
<br />
* "Auto clear the input line after you sent text", should be checked<br />
* "Show the text you sent", should be unchecked<br />
<br />
==Main Window==<br />
To switch between the input line and the main window, please first select a hotkey under the, "Special Options" tab. Your choices are:<br />
* <code>Tab</code><br />
* <code>CTRL+Tab</code><br />
* <code>F6</code><br />
<br />
Once a hotkey has been selected, it will allow you to review text using the following shortcuts -<br />
<br />
{| style="width: 500px; border-bottom:solid 5px #882222;" <br />
! colspan="2" style="color:white; background-color:#882222; text-align:left;" | Output review shortcuts<br />
|- <br />
| style="font-family: monospace, monospace;" | Left, Right, Up, Down<br />
| Navigate letter by letter<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | Ctrl+Left, Ctrl+Right<br />
| Navigate word by word<br />
|- <br />
| style="font-family: monospace, monospace;" | Shift+Left, Right, Up, Down<br />
| Select text letter by letter<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | Ctrl+Shift+Left, Right, Up, Down<br />
| Select text word by word<br />
|- <br />
| style="font-family: monospace, monospace;" | Home<br />
| Go to the beginning of the line<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | Ctrl+Home<br />
| Go to the beginning of the window (first line, first letter)<br />
|- <br />
| style="font-family: monospace, monospace;" | End<br />
| Go to the end of the line<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | Ctrl+End<br />
| Go to the end of the window (last line, last letter)<br />
|- <br />
| style="font-family: monospace, monospace;" | PageUp<br />
| Jump a visual window's height up<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | PageDown<br />
| Jump a visual window's height down<br />
|- <br />
| style="font-family: monospace, monospace;" | Ctrl+C<br />
| Copy selection<br />
|- style="background-color:#ffefef;"<br />
| style="font-family: monospace, monospace;" | Ctrl+Shift+C<br />
| Copy selection as HTML<br />
|}<br />
<br />
== Special Options ==<br />
<br />
Briefly touched on in the section above, there are a few options in this tab of the preferences dialog designed to aid screen reader users.<br />
<br />
=== Announce incoming text in screen reader ===<br />
<br />
Speaks out text coming from the game using the screen reader, on by default. Turning this option off is relevant to [[Accessibility on OSX|macOS]] and [[Accessibility on Linux|Linux]].<br />
<br />
=== Blank Lines ===<br />
<br />
When the game sends blank lines:<br />
* Show them<br />
* Hide them<br />
* Replace with a space<br />
<br />
It may be advantageous to select either of the latter two options, as having blank lines can be problematic on Windows specifically.<br />
<br />
=== Switch To Reviewing Main Window ===<br />
<br />
Switch between input line and main window using:<br />
* <code>Tab</code><br />
* <code>CTRL+Tab</code><br />
* <code>F6</code><br />
<br />
When a key is selected from this dropdown list, it will toggle between placing focus in the main window so that normal cursor commands can be used to review it as well as selecting text and copying it. Note that this should be configured, as it is set to, "No key", by default. N.B. When the tab key is set, the autotab completion functionality will be lost.<br />
<br />
==Nested triggers==<br />
In Mudlet, triggers can have a parent/child relationship. But for those new to creating triggers, this may not be what you want. At this time, this relationship is not indicated by screen readers. To ensure that you are not creating a child trigger, arrow up to the top of the list. You'll hear the announcement, "Triggers". When you do so, and you click the, "Add Item" button, you are guaranteed to create a trigger that is not grouped under one of your previous ones.<br />
<br />
==Trigger navigation==<br />
To quickly navigate between the triggers list, trigger name, patterns list, and the code editor, use <code>Ctrl+Tab</code>. It'll cycle between those elements in exactly that order, allowing you to jump around the screen to the most important parts.<br />
<br />
=Screen Reader and Operating System Specific Information=<br />
<br />
The pages linked below will serve to detail how to use Mudlet with a screen reader. As Mudlet is a cross-platform client, hints and tips to get the most out of using it will be given for each of the platforms it's available on.<br />
<br />
* [[Accessibility On Windows]]<br />
* [[Accessibility on OSX]]<br />
* [[Accessibility on Linux]]<br />
<br />
= Screen reader tips for game admins =<br />
<br />
The following are tips that can help MUD owners/administrators make their games more accessible to screen reader users.<br />
<br />
== Auto-detection ==<br />
Auto-detection of visually impaired players is frowned upon, as it could lead to 'fingerprinting' certain users without their consent. Instead, the best practice is to provide a command for the players that enables a screenreader-friendly mode instead - see StickMUD [https://wiki.stickmud.com/wiki/Screenreader as an example].<br />
<br />
== Sounds ==<br />
<br />
Sounds are a great way of letting a blind or visually impaired user know that something has happened. Especially during fast-paced activities such as combat. They can be as simple as alerts, such as chats or tells, to a full on experience complete with combat sounds, music, and ambiances.<br />
<br />
Sounds can either be sent by the server and downloaded to the client, or can be made using triggers by the player. MSP, GMCP, and MSDP can all be used to accomplish this.<br />
<br />
== Avoid ASCII Art ==<br />
<br />
ASCII art can be a major hindrance to screen reader users. If your MUD has a lot of ASCII art, please consider creating a blind mode, or screen reader mode that can be switched on at any time. Optionally, asking new accounts/characters whether or not they're using a screen reader during character generation and then setting a flag or series of flags to tailor the display is wonderful, because screen reader users do not have to remember a list of options to toggle on and off. ASCII art on the start screen isn't a huge problem, as most often, a blind or visually impaired player will read through it once and then not need to again. The goal here is not to take away anything from sighted players.<br />
<br />
== Tables ==<br />
<br />
Presenting information in tabular format can be a great way to visualize data for a sighted user, but when a screen reader user tries to read this table, they do not have the ability to walk through the cells. This is because, while screen readers do in fact provide table navigation commands, they require markup which isn't present in plain text. Please consider breaking up the information into lines with commas or colons which will make things much clearer. Tables in MUDs can often appear as streams of indecipherable data.<br />
<br />
== more tips? ==<br />
I'd recommend checking out legends of the Jedi as they have done a good effort when it comes to making their mud accessible, just as an example. also you could reach out and talk to us in Mudlet's accessibility channel in discord, we'd be happy to help.<br />
<br />
= Third party packages =<br />
Here are some third party packages which we think are useful for Mudlet.<br />
<br />
== Mudlet Reader package ==<br />
This package provides shortcuts for reading output, and fixes some VoiceOver issues regarding queuing things. It can be installed by using the built-in 'mudlet access reader' alias.<br />
<br />
Download it [https://github.com/tspivey/mudlet-reader/ here].<br />
<br />
== Quick Output ==<br />
This package adds the ability to read the ten most recent lines from the MUD as well as copy a given line to the clipboard. More information can be found [https://github.com/ironcross32/QuickOutput-for-Mudlet here]<br />
<br />
== Channel History ==<br />
This package provides a virtual buffering system for use in triggers which can be reviewed at any time using easy-to-remember hotkeys. Each message that is stored in a buffer is also assigned a category by the trigger author. Thus, things like public chats, tells, game announcements, etc. can each have a separate category. To learn more about this package, click [https://github.com/ironcross32/ChannelHistory here].</div>Vadihttps://wiki.mudlet.org/index.php?title=Bounty_Process&diff=20453Bounty Process2023-05-13T14:59:50Z<p>Vadi: Added bounty transfers</p>
<hr />
<div>This is a guide for Mudlet developers on how to manage a bounty program for Mudlet - where a bounty program an incentive program that rewards open-source developers (Mudlet developers or outside) for fixing issues on an open source project. Here are the steps to follow:<br />
<br />
# Inquire with the core development team to gauge their interest in picking issues to include in the bounty program.<br />
# Dev team members should pick out issues they would like to see in the bounty program and label them as being worth $20, $30, or $50 worth of work. This process can be done asynchronously and in a Github project (kept private - having it public led to confusion).<br />
# Once the issues have been identified, the team should get together and rotate turns picking issues out in a synchronous manner. The team should do rounds of 50 issues, then 30, then 20 to ensure an even spread of issue complexity in the bounty program.<br />
# Once the issues have been selected, put the bounties up.<br />
# Developers will come and solve issues. When the team feels comfortable with the developer's identity, they should pay them on the specified PayPal account of the bounty taker. If the team feels the need to verify the identity of the developer, they should ask them to post or edit an existing comment with a particular (but random each time) text.<br />
# The team should take the time to solve an issue to a good level. They should try to give most feedback upfront so that developers do not feel they are being "led around."<br />
# Once the pull request (PR) is merged, the team should pay out to the bounty taker immediately in PayPal.<br />
## Alternatively, it is also possible for the bounty taker to request the bounty to be transferred to another bounty instead of paying it out, if they wish.<br />
<br />
2023 is the first year we're starting with a pilot bounty, so expect this process to be refined and improved as we go.</div>Vadihttps://wiki.mudlet.org/index.php?title=Manual:Mudlet_Object_Functions&diff=20449Manual:Mudlet Object Functions2023-05-06T05:14:27Z<p>Vadi: /* setScript */ clarify example</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.}}<br />
= Mudlet Object Functions =<br />
Collection of functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.<br />
<br />
==addCmdLineSuggestion==<br />
;addCmdLineSuggestion([name], suggestion)<br />
: Add suggestion for tab completion for specified command line.<br />
<br />
: For example, start typing ''he'' and hit ''TAB'' until ''help'' appears in command line.<br />
: Non-word characters are skipped (this is the reason why they can't be added at start of suggestion), therefore it's also possible to type: ''/he'' and hit ''TAB''.<br />
<br />
: See also: [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - suggestion as a single word to add to tab completion (only the following are allowed: ''0-9A-Za-z_'')<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
addCmdLineSuggestion("help")<br />
<br />
local suggestions = {"Pneumonoultramicroscopicsilicovolcanoconiosis", "supercalifragilisticexpialidocious", "serendipitous"}<br />
for _, suggestion in ipairs(suggestions) do<br />
addCmdLineSuggestion(suggestion)<br />
end<br />
</syntaxhighlight><br />
<br />
==adjustStopWatch==<br />
;adjustStopWatch(watchID/watchName, amount)<br />
: Adjusts the elapsed time on the stopwatch forward or backwards by the amount of time. It will work even on stopwatches that are not running, and thus can be used to preset a newly created stopwatch with a negative amount so that it runs down from a negative time towards zero at the preset time.<br />
<br />
;Parameters<br />
* watchID (number) / watchName (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* amount (decimal number): An amount in seconds to adjust the stopwatch by, positive amounts increase the recorded elapsed time.<br />
<br />
;Returns<br />
* true on success if the stopwatch was found and thus adjusted, or nil and an error message if not.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- demo of a persistent stopWatch used to real time a mission<br />
-- called with a positive number of seconds it will start a "missionStopWatch"<br />
-- unless there already is one in which case it will instead report on<br />
-- the deadline. use 'stopStopWatch("missionStopWatch")' when the mission<br />
-- is done and 'deleteStopWatch("missionStopWatch")' when the existing mission<br />
-- is to be disposed of. Until then repeated use of 'mission(interval)' will<br />
-- just give updates...<br />
function mission(time)<br />
local missionTimeTable = missionTimeTable or {}<br />
<br />
if createStopWatch("missionStopWatch") then<br />
adjustStopWatch("missionStopWatch", -tonumber(time))<br />
setStopWatchPersistence("missionStopWatch", true)<br />
missionTimeTable = getStopWatchBrokenDownTime("missionStopWatch")<br />
<br />
echo(string.format("Get cracking, you have %02i:%02i:%02i hg:m:s left.\n", missionTimeTable.hours, missionTimeTable.minutes, missionTimeTable.seconds))<br />
startStopWatch("missionStopWatch")<br />
else<br />
-- it already exists, so instead report what is/was the time on it<br />
--[=[ We know that the stop watch exists - we just need to find the ID<br />
so we can get the running detail which is only available from the getStopWatches()<br />
table and that is indexed by ID]=]<br />
for k,v in pairs(getStopWatches()) do<br />
if v.name == "missionStopWatch" then<br />
missionTimeTable = v<br />
end<br />
end<br />
if missionTimeTable.isRunning then<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Better hurry up, the clock is ticking on an existing mission and you only have %02i:%02i:%02i h:m:s left.\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Bad news, you are past the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
else<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Well done! You have already completed a mission %02i:%02i:%02i h:m:s before the deadline ...\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Uh oh! You failed to meet the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
end<br />
end<br />
end<br />
<br />
<br />
-- in use:<br />
lua mission(60*60)<br />
Get cracking, you have 01:00:00 h:m:s left.<br />
<br />
lua mission(60*60)<br />
Better hurry up, the clock is ticking on an existing mission and you only have 00:59:52 h:m:s left.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==appendScript==<br />
;appendScript(scriptName, luaCode, [occurrence])<br />
: Appends Lua code to the script "scriptName". If no occurrence given it sets the code of the first found script.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#setScript|setScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script<br />
* ''luaCode'': scripts luaCode to append<br />
* ''occurence'': (optional) the occurrence of the script in case you have many with the same name<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of appending the script lua code to the first occurrence of "testscript"<br />
appendScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==appendCmdLine==<br />
;appendCmdLine([name], text)<br />
: Appends text to the main input line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]], [[#clearCmdLine|clearCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the text will be appended to the main commandline.<br />
* ''text'': text to append<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- adds the text "55 backpacks" to whatever is currently in the input line<br />
appendCmdLine("55 backpacks")<br />
<br />
-- makes a link, that when clicked, will add "55 backpacks" to the input line<br />
echoLink("press me", "appendCmdLine'55 backpack'", "Press me!")<br />
</syntaxhighlight><br />
<br />
==clearCmdLine==<br />
;clearCmdLine([name])<br />
: Clears the input line of any text that's been entered.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the main commandline's text will be cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- don't be evil with this!<br />
clearCmdLine()<br />
</syntaxhighlight><br />
<br />
==clearCmdLineSuggestions==<br />
;clearCmdLineSuggestions([name])<br />
<br />
: Clears all suggestions for command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
;Parameter<br />
* ''name'': (optional) name of the command line. If not given the main commandline's suggestions will be cleared.<br />
<br />
<syntaxhighlight lang="lua"><br />
clearCmdLineSuggestions()<br />
</syntaxhighlight><br />
<br />
==createStopWatch==<br />
;createStopWatch([name], [start immediately])<br />
;createStopWatch([start immediately])<br />
Before Mudlet 4.4.0:<br />
;createStopWatch()<br />
<br />
: This function creates a stopwatch, a high resolution time measurement tool. Stopwatches can be started, stopped, reset, asked how much time has passed since the stop watch has been started and, following an update for Mudlet 4.4.0: be adjusted, given a name and be made persistent between sessions (so can time real-life things). Prior to 4.4.0 the function took no parameters '''and the stopwatch would start automatically when it was created'''.<br />
<br />
;Parameters:<br />
* ''start immediately'' (bool) used to override the behaviour prior to Mudlet 4.4.0 so that if it is the ''only'' argument then a ''false'' value will cause the stopwatch to be created but be in a ''stopped'' state, however if a name parameter is provided then this behaviour is assumed and then a ''true'' value is required should it be desired for the stopwatch to be started on creation. This difference between the cases with and without a name argument is to allow for older scripts to continue to work with 4.4.0 or later versions of Mudlet without change, yet to allow for more functionality - such as presetting a time when the stopwatch is created but not to start it counting down until some time afterwards - to be performed as well with a named stopwatch.<br />
<br />
* ''name'' (string) a ''unique'' text to use to identify the stopwatch.<br />
<br />
;Returns:<br />
* the ID (number) of a stopwatch; or, from '''4.4.0''': a nil + error message if the name has already been used.<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#resetStopWatch|resetStopWatch()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] or, from 4.4.0: [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatches|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]], [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]], [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]]<br />
<br />
;Example<br />
: (Prior to Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system and store the respective stopWatch-IDs in global variables:<br />
<syntaxhighlight lang="lua"><br />
fightStopWatch = fightStopWatch or createStopWatch() -- create, or re-use a stopwatch, and store the watchID in a global variable to access it from anywhere<br />
<br />
-- then you can start the stop watch in some trigger/alias/script with:<br />
startStopWatch(fightStopWatch)<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch(fightStopWatch)<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch(fightStopWatch)<br />
</syntaxhighlight><br />
<br />
: (From Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system with unique names:<br />
<syntaxhighlight lang="lua"><br />
createStopWatch("fightStopWatch") -- creates the stopwatch or returns nil+msg if it already exists<br />
<br />
-- then you can start the stop watch (if it is not already started) in some trigger/alias/script with:<br />
startStopWatch("fightStopWatch")<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch("fightStopWatch")<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch("fightStopWatch")<br />
</syntaxhighlight><br />
<br />
:You can also measure the elapsed time without having to stop the stop watch (equivalent to getting a ''lap-time'') with [[#getStopWatchTime|getStopWatchTime()]].<br />
<br />
{{note}} it's best to re-use stopwatch IDs if you can for Mudlet prior to 4.4.0 as they cannot be deleted, so creating more and more would use more memory. From 4.4.0 the revised internal design has been changed such that there are no internal timers created for each stopwatch - instead either a timestamp or a fixed elapsed time record is used depending on whether the stopwatches is running or stopped so that there are no "moving parts" in the later design and less resources are used - and they can be removed if no longer required.<br />
<br />
==deleteAllNamedTimers==<br />
; deleteAllNamedTimers(userName)<br />
<br />
:Deletes all named timers and prevents them from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteAllNamedTimers("Demonnic") -- emergency stop or debugging situation, most likely.<br />
</syntaxhighlight><br />
<br />
==deleteNamedTimer==<br />
; success = deleteNamedTimer(userName, handlerName)<br />
<br />
:Deletes a named timer with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local deleted = deleteNamedTimer("Demonnic", "DemonVitals")<br />
if deleted then<br />
cecho("DemonVitals deleted forever!!")<br />
else<br />
cecho("DemonVitals doesn't exist and so could not be deleted.")<br />
end<br />
</syntaxhighlight><br />
<br />
==deleteStopWatch==<br />
;deleteStopWatch(watchID/watchName)<br />
<br />
: This function removes an existing stopwatch, whether it only exists for this session or is set to be otherwise saved between sessions by using [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]] with a ''true'' argument. <br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns:<br />
* ''true'' if the stopwatch was found and thus deleted, or ''nil'' and an error message if not - obviously using it twice with the same argument will fail the second time unless another one with the same name or ID was recreated before the second use. Note that an empty string as a name ''will'' find the lowest ID numbered ''unnamed'' stopwatch and that will then find the next lowest ID number of unnamed ones until there are none left, if used repetitively!<br />
<br />
<syntaxhighlight lang="lua"><br />
lua MyStopWatch = createStopWatch("stopwatch_mine")<br />
true<br />
<br />
lua display(MyStopWatch)<br />
4<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
true<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
nil<br />
<br />
"stopwatch with id 4 not found"<br />
<br />
lua deleteStopWatch("stopwatch_mine")<br />
nil<br />
<br />
"stopwatch with name "stopwatch_mine" not found"<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]],<br />
<br />
{{MudletVersion|4.4}}<br />
<br />
{{note}} Stopwatches that are not set to be persistent will be deleted automatically at the end of a session (or if [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] is called).<br />
<br />
==removeCmdLineSuggestion==<br />
;removeCmdLineSuggestion([name], suggestion)<br />
: Remove a suggestion for tab completion for specified command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - text to add to tab completion, non words characters at start and end of word should not be used (all characters except: `0-9A-Za-z_`)<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
removeCmdLineSuggestion("help")<br />
</syntaxhighlight><br />
<br />
==disableAlias==<br />
;disableAlias(name)<br />
:Disables/deactivates the alias by its name. If several aliases have this name, they'll all be disabled. If you disable an alias group, all the aliases inside the group will be disabled as well.<br />
<br />
: See also: [[#enableAlias|enableAlias()]], [[#disableTrigger|disableTrigger()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the alias. Passed as a string.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--Disables the alias called 'my alias'<br />
disableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==disableKey==<br />
;disableKey(name)<br />
:Disables key a key (macro) or a key group. When you disable a key group, all keys within the group will be implicitly disabled as well.<br />
<br />
: See also: [[#enableKey|enableKey()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the key or group to identify what you'd like to disable.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could set multiple keys on the F1 key and swap their use as you wish by disabling and enabling them<br />
disableKey("attack macro")<br />
disableKey("jump macro")<br />
enableKey("greet macro")<br />
</syntaxhighlight><br />
<br />
==disableScript==<br />
;disableScript(name)<br />
:Disables a script that was previously enabled. Note that disabling a script only stops it from running in the future - it won't "undo" anything the script has made, such as labels on the screen.<br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#enableScript|enableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the script called 'my script'<br />
disableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==disableTimer==<br />
;disableTimer(name)<br />
:Disables a timer from running it’s script when it fires - so the timer cycles will still be happening, just no action on them. If you’d like to permanently delete it, use [[Manual:Lua_Functions#killTrigger|killTrigger]] instead.<br />
<br />
: See also: [[#enableTimer|enableTimer()]], [[#disableTrigger|disableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the timer called 'my timer'<br />
disableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
==disableTrigger==<br />
;disableTrigger(name)<br />
:Disables a permanent (one in the trigger editor) or a temporary trigger. When you disable a group, all triggers inside the group are disabled as well<br />
<br />
: See also: [[#enableTrigger|enableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Disables the trigger called 'my trigger'<br />
disableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
==enableAlias==<br />
;enableAlias(name)<br />
:Enables/activates the alias by it’s name. If several aliases have this name, they’ll all be enabled.<br />
<br />
: See also: [[#disableAlias|disableAlias()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the alias ID that was returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] on creation of the alias or the name of the alias in case of a GUI alias.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Enables the alias called 'my alias'<br />
enableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==enableKey==<br />
;enableKey(name)<br />
:Enables a key (macro) or a group of keys (and thus all keys within it that aren't explicitly deactivated).<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the group that identifies the key.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could use this to disable one key set for the numpad and activate another<br />
disableKey("fighting keys")<br />
enableKey("walking keys")<br />
</syntaxhighlight><br />
{{note}} From Version '''3.10'' returns ''true'' if one or more keys or groups of keys were found that matched the name given or ''false'' if not; prior to then it returns ''true'' if there were '''any''' keys - whether they matched the name or not!<br />
<br />
==enableScript==<br />
;enableScript(name)<br />
:Enables / activates a script that was previously disabled. <br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<syntaxhighlight lang="lua"><br />
-- enable the script called 'my script' that you created in Mudlet's script section<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==enableTimer==<br />
;enableTimer(name)<br />
:Enables or activates a timer that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<syntaxhighlight lang="lua"><br />
-- enable the timer called 'my timer' that you created in Mudlets timers section<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTimer you've made<br />
timerID = tempTimer(10, [[echo("hi!")]])<br />
<br />
-- it won't go off now<br />
disableTimer(timerID)<br />
-- it will continue going off again<br />
enableTimer(timerID)<br />
</syntaxhighlight><br />
<br />
==enableTrigger==<br />
;enableTrigger(name)<br />
:Enables or activates a trigger that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or by any other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<syntaxhighlight lang="lua"><br />
-- enable the trigger called 'my trigger' that you created in Mudlets triggers section<br />
enableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTrigger you've made<br />
triggerID = tempTrigger("some text that will match in a line", [[echo("hi!")]])<br />
<br />
-- it won't go off now when a line with matching text comes by<br />
disableTrigger(triggerID)<br />
<br />
-- and now it will continue going off again<br />
enableTrigger(triggerID)<br />
</syntaxhighlight><br />
<br />
==exists==<br />
;exists(name/IDnumber, type)<br />
:Returns the number of things with the given name or number of the given type - and 0 if none are present. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
:See also: [[#isActive|isActive(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. exists("my trigger", "trigger") .. " triggers called 'my trigger'!")<br />
</syntaxhighlight><br />
<br />
: You can also use this alias to avoid creating duplicate things, for example:<br />
<syntaxhighlight lang="lua"><br />
-- this code doesn't check if an alias already exists and will keep creating new aliases<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
<br />
-- while this code will make sure that such an alias doesn't exist first<br />
-- we do == 0 instead of 'not exists' because 0 is considered true in Lua<br />
if exists("Attack", "alias") == 0 then<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
end<br />
</syntaxhighlight><br />
<br />
: Especially helpful when working with [[Manual:Lua_Functions#permTimer|permTimer]]:<br />
<syntaxhighlight lang="lua"><br />
if not exists("My animation timer", "timer") then<br />
vdragtimer = permTimer("My animation timer", "", .016, onVDragTimer) -- 60fps timer!<br />
end<br />
<br />
enableTimer("My animation timer")<br />
</syntaxhighlight><br />
<br />
{{Note}} A positive ID number will return either a ''1'' or ''0'' value and not a lua boolean ''true'' or ''false'' as might otherwise be expected, this is for constancy with the way the function behaves for a name.<br />
<br />
==getButtonState==<br />
;getButtonState([ButtonNameOrID])<br />
:This function can be used within checkbox button scripts (2-state buttons) to determine the current state of the checkbox.<br />
<br />
: See also: [[#setButtonState|setButtonState()]].<br />
{{note}} Function can be used in any Mudlet script outside of a button's own script with parameter ButtonNameOrID available from Mudlet version 4.13.0+<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: a numerical ID or string name to identify the checkbox button.<br />
<br />
;Returns <br />
* ''2'' if the button has "checked" state, or ''1'' if the button is not checked. (or a ''nil'' and an error message if ButtonNameOrID did not identify a check-able button)<br />
<br />
;Example <br />
<syntaxhighlight lang="lua"><br />
-- check from within the script of a check-able button:<br />
local checked = getButtonState()<br />
if checked == 1 then<br />
hideExits()<br />
else<br />
showExits()<br />
end<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- check from anywhere in another Lua script of the same profile (available from Mudlet 4.13.0)<br />
local checked, errMsg = getButtonState("Sleep")<br />
if checked then<br />
shouldBeMounted = shouldBeMounted or false<br />
sendAll("wake", "stand")<br />
if shouldBeMounted then<br />
send("mount horse")<br />
end<br />
else<br />
-- Global used to record if we were on a horse before our nap:<br />
shouldBeMounted = mounted or false<br />
if shouldBeMounted then<br />
send("dismount")<br />
end<br />
sendAll("sit", "sleep")<br />
end<br />
</syntaxhighlight><br />
<br />
==getCmdLine==<br />
;getCmdLine([name])<br />
: Returns the current content of the given command line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, it returns the text of the main commandline.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replaces whatever is currently in the input line by "55 backpacks"<br />
printCmdLine("55 backpacks")<br />
<br />
--prints the text "55 backpacks" to the main console<br />
echo(getCmdLine())<br />
</syntaxhighlight><br />
<br />
==getConsoleBufferSize==<br />
;local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize([consoleName])<br />
:Returns, on success, the maximum number of lines a buffer (main window or a miniconsole) can hold and how many will be removed at a time when that limit is exceeded; returns a ''nil'' and an error message on failure.<br />
: See also: [[Manual:Mudlet_Object_Functions#setConsoleBufferSize|setConsoleBufferSize()]]<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main window's size and how many lines will be deleted<br />
-- when it gets to that size to be as small as possible:<br />
setConsoleBufferSize("main", 1, 1)<br />
true<br />
<br />
-- find out what the numbers are:<br />
local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize()<br />
echo("\nWhen the main console gets to " .. lineLimit .. " lines long, the first " .. sizeOfBatchDeletion .. " lines will be removed.\n")<br />
When the main console gets to 100 lines long, the first 1 lines will be removed.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.17}}<br />
<br />
==getNamedTimers==<br />
; timers = getNamedTimers(userName)<br />
<br />
:Returns a list of all the named timers' names as a table.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Returns <br />
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- {}<br />
registerNamedTimer("Test1", "testEvent", "testFunction")<br />
registerNamedTimer("Test2", "someOtherEvent", myHandlerFunction)<br />
timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- { "Test1", "Test2" }<br />
</syntaxhighlight><br />
<br />
== getProfileStats==<br />
;getProfileStats()<br />
<br />
:Returns a table with profile statistics for how many triggers, patterns within them, aliases, keys, timers, and scripts the profile has. Similar to the Statistics button in the script editor, accessible to Lua scripting.<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show all stats<br />
display(getProfileStats())<br />
<br />
-- check how many active triggers there are<br />
activetriggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{activetriggers}<PaleGreen> active triggers!\n")<br />
<br />
-- triggers can have many patterns, so let's check that as well<br />
patterns = getProfileStats().triggers.patterns.active<br />
triggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{patterns}<PaleGreen> active patterns within <SlateGrey>{triggers}<PaleGreen> triggers!\n")<br />
</syntaxhighlight><br />
<br />
==getStopWatches==<br />
;table = getStopWatches()<br />
<br />
: Returns a table of the details for each stopwatch in existence, the keys are the watch IDs but since there can be gaps in the ID number allocated for the stopwatches it will be necessary to use the ''pairs(...)'' rather than the ''ipairs(...)'' method to iterate through all of them in ''for'' loops!<br />
: Each stopwatch's details will list the following items: ''name'' (string), ''isRunning'' (boolean), ''isPersistent'' (boolean), ''elapsedTime'' (table). The last of these contains the same data as is returned by the results table from the [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]] function - namely ''days'' (positive integer), ''hours'' (integer, 0 to 23), ''minutes'' (integer, 0 to 59), ''second'' (integer, 0 to 59), ''milliSeconds'' (integer, 0 to 999), ''negative'' (boolean) with an additional ''decimalSeconds'' (number of seconds, with a decimal portion for the milli-seconds and possibly a negative sign, representing the whole elapsed time recorded on the stopwatch) - as would also be returned by the [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] function.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- on the command line:<br />
lua getStopWatches()<br />
-- could return something like:<br />
{<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 15,<br />
seconds = 2,<br />
negative = false,<br />
milliSeconds = 66,<br />
hours = 0,<br />
days = 18,<br />
decimalSeconds = 1556102.066<br />
},<br />
name = "Playing time",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 47,<br />
seconds = 1,<br />
negative = true,<br />
milliSeconds = 657,<br />
hours = 23,<br />
days = 2,<br />
decimalSeconds = -258421.657<br />
},<br />
name = "TMC Vote",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 26,<br />
seconds = 36,<br />
negative = false,<br />
milliSeconds = 899,<br />
hours = 3,<br />
days = 0,<br />
decimalSeconds = 12396.899<br />
},<br />
name = "",<br />
isRunning = false<br />
},<br />
[5] = {<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 0,<br />
seconds = 38,<br />
negative = false,<br />
milliSeconds = 763,<br />
hours = 0,<br />
days = 0,<br />
decimalSeconds = 38.763<br />
},<br />
name = "",<br />
isRunning = true<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==getStopWatchTime==<br />
;time = getStopWatchTime(watchID [or watchName from Mudlet 4.4.0])<br />
: Returns the time as a decimal number of seconds with up to three decimal places to give a milli-seconds (thousandths of a second) resolution.<br />
: Please note that, prior to 4.4.0 it was not possible to retrieve the elapsed time after the stopwatch had been stopped, retrieving the time was not possible as the returned value then was an indeterminate, meaningless time; from the 4.4.0 release, however, the elapsed value can be retrieved at any time, even if the stopwatch has not been started since creation or modified with the [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]] function introduced in that release.<br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]].<br />
<br />
:Returns a number<br />
<br />
;Parameters<br />
* ''watchID''<br />
: The ID number of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of showing the time left on the stopwatch<br />
teststopwatch = teststopwatch or createStopWatch()<br />
startStopWatch(teststopwatch)<br />
echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))<br />
tempTimer(1, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
tempTimer(2, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
stopStopWatch(teststopwatch)<br />
</syntaxhighlight><br />
<br />
==getStopWatchBrokenDownTime==<br />
; brokenDownTimeTable = getStopWatchBrokenDownTime(watchID or watchName)<br />
: Returns the current stopwatch time, whether the stopwatch is running or is stopped, as a table, broken down into:<br />
* "days" (integer)<br />
* "hours" (integer, 0 to 23)<br />
* "minutes" (integer, 0 to 59)<br />
* "seconds" (integer, 0 to 59)<br />
* "milliSeconds" (integer, 0 to 999)<br />
* "negative" (boolean, true if value is less than zero)<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]].<br />
<br />
;Parameters<br />
* ''watchID'' / ''watchName''<br />
: The ID number or the name of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--an example, showing the presetting of a stopwatch.<br />
<br />
--This will fail if the stopwatch with the given name<br />
-- already exists, but then we can use the existing one:<br />
local watchId = createStopWatch("TopMudSiteVoteStopWatch")<br />
if watchId ~= nil then<br />
-- so we have just created the stopwatch, we want it<br />
-- to be saved for future sessions:<br />
setStopWatchPersistence("TopMudSiteVoteStopWatch", true)<br />
-- and set it to count down the 12 hours until we can<br />
-- revote:<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
-- and start it running<br />
startStopWatch("TopMudSiteVoteStopWatch")<br />
<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
end<br />
<br />
--[[ now I can check when it is time to vote again, even when<br />
I stop the session and restart later by running the following<br />
from a perm timer - perhaps on a 15 minute interval. Note that<br />
when loaded in a new session the Id it gets is unlikely to be<br />
the same as that when it was created - but that is not a<br />
problem as the name is preserved and, if the timer is running<br />
when the profile is saved at the end of the session then the<br />
elapsed time will continue to increase to reflect the real-life<br />
passage of time:]]<br />
<br />
local voteTimeTable = getStopWatchBrokenDownTime("TopMudSiteVoteStopWatch")<br />
<br />
if voteTimeTable["negative"] then<br />
if voteTimeTable["hours"] == 0 and voteTimeTable["minutes"] < 30 then<br />
echo("Voting for WotMUD on Top Mud Site in " .. voteTimeTable["minutes"] .. " minutes...")<br />
end<br />
else<br />
echo("Oooh, it is " .. voteTimeTable["days"] .. " days, " .. voteTimeTable["hours"] .. " hours and " .. voteTimeTable["minutes"] .. " minutes past the time to Vote on Top Mud Site - doing it now!")<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
resetStopWatch("TopMudSiteVoteStopWatch")<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==getScript==<br />
; getScript(scriptName, [occurrence])<br />
: Returns the script with the given name. If you have more than one script with the same name, specify the occurrence to pick a different one. Returns -1 if the script doesn't exist.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#setScript|setScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script.<br />
* ''occurrence'': (optional) occurence of the script in case you have many with the same name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the "New script" on screen<br />
print(getScript("New script"))<br />
<br />
-- an example of returning the script Lua code from the second occurrence of "testscript"<br />
test_script_code = getScript("testscript", 2)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==invokeFileDialog==<br />
;invokeFileDialog(fileOrFolder, dialogTitle)<br />
:Opens a file chooser dialog, allowing the user to select a file or a folder visually. The function returns the selected path or "" if there was none chosen.<br />
<br />
;Parameters<br />
* ''fileOrFolder:'' ''true'' for file selection, ''false'' for folder selection.<br />
* ''dialogTitle'': what to say in the window title.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
function whereisit()<br />
local path = invokeFileDialog(false, "Where should we save the file? Select a folder and click Open")<br />
<br />
if path == "" then return nil else return path end<br />
end<br />
</syntaxhighlight><br />
<br />
==isActive==<br />
;isActive(name/IDnumber, type)<br />
:You can use this function to check if something, or somethings, are active. <br />
:Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
: See also: [[#exists|exists(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!")<br />
<br />
-- Can also be used to check if a specific item is enabled or not.<br />
if isActive("spellname", "trigger" > 0 then<br />
-- the spellname trigger is active<br />
else<br />
-- it is not active<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}} A positive ID number that does not exist will still return a ''0'' value, this is for constancy with the way the function behaves for a name that does not refer to any item either. If necessary the existence of an item should be confirmed with [[#exists|exists(...)]] first.<br />
<br />
==isPrompt==<br />
;isPrompt()<br />
:Returns true or false depending on if the line at the cursor position is a prompt. This infallible feature is available for games that supply GA events (to check if yours is one, look to bottom-right of the main window - if it doesn’t say <No GA>, then it supplies them).<br />
<br />
:Example use could be as a Lua function, making closing gates on a prompt real easy.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a trigger pattern with 'Lua function', and this will trigger on every prompt!<br />
return isPrompt()<br />
</syntaxhighlight><br />
<br />
==killAlias==<br />
;killAlias(aliasID)<br />
:Deletes a temporary alias with the given ID.<br />
<br />
;Parameters<br />
* ''aliasID:''<br />
: The id returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] to identify the alias.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- deletes the alias with ID 5<br />
killAlias(5)<br />
</syntaxhighlight><br />
<br />
==killKey==<br />
;killKey(name)<br />
:Deletes a keybinding with the given name. If several keybindings have this name, they'll all be deleted.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name or the id returned by [[Manual:Lua_Functions#tempKey|tempKey]] to identify the key.<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
<syntaxhighlight lang="lua"><br />
-- make a temp key<br />
local keyid = tempKey(mudlet.key.F8, [[echo("hi!")]])<br />
<br />
-- delete the said temp key<br />
killKey(keyid)<br />
</syntaxhighlight><br />
<br />
==killTimer==<br />
;killTimer(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
{{note}} Non-temporary timers that you have set up in the GUI or by using [[#permTimer|permTimer]] cannot be deleted with this function. Use [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#enableTimer|enableTimer()]] to turn them on or off.<br />
<br />
;Parameters<br />
* ''id:'' the ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
: Returns true on success and false if the timer id doesn’t exist anymore (timer has already fired) or the timer is not a temp timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the timer and remember the timer ID<br />
timerID = tempTimer(10, [[echo("hello!")]])<br />
<br />
-- delete the timer<br />
killTimer(timerID)<br />
-- reset the reference to it<br />
timerID = nil<br />
</syntaxhighlight><br />
<br />
==killTrigger==<br />
;killTrigger(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTrigger]], or a trigger made with one of the ''temp<type>Trigger()'' functions.<br />
<br />
{{note}} When used in out of trigger contexts, the triggers are disabled and deleted upon the next line received from the game - so if you are testing trigger deletion within an alias, the 'statistics' window will be reporting trigger counts that are disabled and pending removal, and thus are no cause for concern.<br />
<br />
;Parameters<br />
* ''id:''<br />
: The ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] to identify the item. ID is a string and not a number.<br />
<br />
:Returns true on success and false if the trigger id doesn’t exist anymore (trigger has already fired) or the trigger is not a temp trigger.<br />
<br />
==permAlias==<br />
;permAlias(name, parent, regex, lua code)<br />
<br />
:Creates a persistent alias that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name you’d like the alias to have.<br />
* ''parent:'' <br />
: The name of the group, or another alias you want the trigger to go in - however if such a group/alias doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''regex:''<br />
: The pattern that you’d like the alias to use.<br />
* ''lua code:'' <br />
: The script the alias will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates an alias called "new alias" in a group called "my group"<br />
permAlias("new alias", "my group", "^test$", [[echo ("say it works! This alias will show up in the script editor too.")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permAlias with the same name will keep creating new aliases. You can check if an alias already exists with the [[Manual:Lua_Functions#exists|exists]] function.<br />
<br />
==permGroup==<br />
;permGroup(name, itemtype, [parent])<br />
<br />
:Creates a new group of a given type. This group will persist through Mudlet restarts. <br />
;Parameters<br />
* ''name'':<br />
: The name of the new group item you want to create.<br />
* ''itemtype'' :<br />
: The type of the item, can be one of the following:<br />
:: trigger<br />
:: alias <br />
:: timer<br />
:: script (available in Mudlet 4.7+)<br />
:: key (available in Mudlet 4.11+)<br />
* ''parent'' (available in Mudlet 3.1+):<br />
: (optional) Name of existing item which the new item will be created as a child of. If none is given, item will be at the root level (not nested in any other groups)<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--create a new trigger group<br />
permGroup("Combat triggers", "trigger")<br />
<br />
--create a new alias group only if one doesn't exist already<br />
if exists("Defensive aliases", "alias") == 0 then<br />
permGroup("Defensive aliases", "alias")<br />
end<br />
</syntaxhighlight><br />
<br />
==permPromptTrigger==<br />
;permPromptTrigger(name, parent, lua code)<br />
:Creates a persistent trigger for the in-game prompt that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead (GA) or End-of-Record (EOR) to be enabled in your game. Available in Mudlet 3.6+<br />
<br />
;Parameters:<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
permPromptTrigger("echo on prompt", "", [[echo("hey! this thing is working!\n")]])<br />
</syntaxhighlight><br />
<br />
<br />
==permRegexTrigger==<br />
;permRegexTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger with one or more ''regex'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a regex trigger that will match on the prompt to record your status<br />
permRegexTrigger("Prompt", "", {"^(\d+)h, (\d+)m"}, [[health = tonumber(matches[2]); mana = tonumber(matches[3])]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permRegexTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permBeginOfLineStringTrigger==<br />
;permBeginOfLineStringTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger that stays after Mudlet is restarted and shows up in the Script Editor. The trigger will go off whenever one of the ''regex'' patterns it's provided with matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger that will match on anything that starts with "You sit" and do "stand".<br />
-- It will not go into any groups, so it'll be on the top.<br />
permBeginOfLineStringTrigger("Stand up", "", {"You sit"}, [[send ("stand")]])<br />
<br />
-- Another example - lets put our trigger into a "General" folder and give it several patterns.<br />
permBeginOfLineStringTrigger("Stand up", "General", {"You sit", "You fall", "You are knocked over by"}, [[send ("stand")]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permBeginOfLineStringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permSubstringTrigger==<br />
;permSubstringTrigger( name, parent, pattern table, lua code )<br />
:Creates a persistent trigger with one or more ''substring'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger to highlight the word "pixie" for us<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie"},<br />
[[selectString(line, 1) bg("yellow") resetFormat()]])<br />
<br />
-- Or another trigger to highlight several different things<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie", "cat", "dog", "rabbit"},<br />
[[selectString(line, 1) fg ("blue") bg("yellow") resetFormat()]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permSubstringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permScript==<br />
;permScript(name, parent, lua code)<br />
: Creates a new script in the Script Editor that stays after Mudlet is restarted.<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
* ''parent'': name of the script group you want the script to go in.<br />
* ''lua code'': is the code with string you are putting in your script.<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
: See also: [[#enableScript|enableScript()]], [[#exists|exists()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a script in the "first script group" group<br />
permScript("my script", "first script group", [[send ("my script that's in my first script group fired!")]])<br />
-- create a script that's not in any group; just at the top<br />
permScript("my script", "", [[send ("my script that's in my first script group fired!")]])<br />
<br />
-- enable Script - a script element is disabled at creation<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{note}} The script is called once but NOT active after creation, it will need to be enabled by [[#enableScript|enableScript()]].<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permScript with the same name will keep creating new script elements. You can check if a script already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
{{note}} If the ''lua code'' parameter is an empty string, then the function will create a script group instead.<br />
<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==permTimer==<br />
;permTimer(name, parent, seconds, lua code)<br />
: Creates a persistent timer that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the timer.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in.<br />
* ''seconds'' <br />
:a floating point number specifying a delay in seconds after which the timer will do the lua code (stored as the timer's "script") you give it as a string.<br />
* ''lua code'' is the code with string you are doing this to.<br />
<br />
;Returns<br />
* a unique id number for that timer.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a timer in the "first timer group" group<br />
permTimer("my timer", "first timer group", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
-- create a timer that's not in any group; just at the top<br />
permTimer("my timer", "", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
<br />
-- enable timer - they start off disabled until you're ready<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
{{note}} The timer is NOT active after creation, it will need to be enabled by a call to [[#enableTimer|enableTimer()]] before it starts.<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permTimer with the same name will keep creating new timers. You can check if a timer already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permKey==<br />
;permKey(name, parent, [modifier], key code, lua code)<br />
: Creates a persistent key that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the key.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in or "" for the top level.<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
: set to -1 if you want to create a key folder instead.<br />
* ''lua code'<br />
: code you would like the key to run.<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
{{MudletVersion|3.2+, creating key folders in Mudlet 4.10}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a key at the top level for F8<br />
permKey("my key", "", mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- or Ctrl+F8<br />
permKey("my key", "", mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- Ctrl+Shift+W<br />
permKey("jump keybinding", "", mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permKey with the same name will keep creating new keys. You can check if a key already exists with the [[Manual:Lua_Functions#exists|exists()]] function. The key will be created even if the lua code does not compile correctly - but this will be apparent as it will be seen in the Editor.<br />
<br />
==printCmdLine==<br />
;printCmdLine([name], text)<br />
<br />
: Replaces the current text in the input line, and sets it to the given text.<br />
: See also: [[Manual:Lua_Functions#clearCmdLine|clearCmdLine()]], [[#appendCmdLine|appendCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, main commandline's text will be set.<br />
* ''text'': text to set<br />
<br />
<syntaxhighlight lang="lua"><br />
printCmdLine("say I'd like to buy ")<br />
</syntaxhighlight><br />
<br />
==raiseEvent==<br />
;raiseEvent(event_name, arg-1, … arg-n)<br />
<br />
: Raises the event event_name. The event system will call the main function (the one that is called exactly like the script name) of all such scripts in this profile that have registered event handlers. If an event is raised, but no event handler scripts have been registered with the event system, the event is ignored and nothing happens. This is convenient as you can raise events in your triggers, timers, scripts etc. without having to care if the actual event handling has been implemented yet - or more specifically how it is implemented. Your triggers raise an event to tell the system that they have detected a certain condition to be true or that a certain event has happened. How - and if - the system is going to respond to this event is up to the system and your trigger scripts don’t have to care about such details. For small systems it will be more convenient to use regular function calls instead of events, however, the more complicated your system will get, the more important events will become because they help reduce complexity very much.<br />
<br />
:The corresponding event handlers that listen to the events raised with raiseEvent() need to use the script name as function name and take the correct number of arguments. <br />
<br />
:See also: [[#raiseGlobalEvent|raiseGlobalEvent]]<br />
<br />
{{note}} possible arguments can be string, number, boolean, table, function, or nil.<br />
<br />
;Example:<br />
<br />
:raiseEvent("fight") a correct event handler function would be: myScript( event_name ). In this example raiseEvent uses minimal arguments, name the event name. There can only be one event handler function per script, but a script can still handle multiple events as the first argument is always the event name - so you can call your own special handlers for individual events. The reason behind this is that you should rather use many individual scripts instead of one huge script that has all your function code etc. Scripts can be organized very well in trees and thus help reduce complexity on large systems.<br />
<br />
Where the number of arguments that your event may receive is not fixed you can use [http://www.lua.org/manual/5.1/manual.html#2.5.9 ''...''] as the last argument in the ''function'' declaration to handle any number of arguments. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- try this function out with "lua myscripthandler(1,2,3,4)"<br />
function myscripthandler(a, b, ...)<br />
print("Arguments a and b are: ", a,b)<br />
-- save the rest of the arguments into a table<br />
local otherarguments = {...}<br />
print("Rest of the arguments are:")<br />
display(otherarguments)<br />
<br />
-- access specific otherarguments:<br />
print("First and second otherarguments are: ", otherarguments[1], otherarguments[2])<br />
end<br />
</syntaxhighlight><br />
<br />
==raiseGlobalEvent==<br />
;raiseGlobalEvent(event_name, arg-1, … arg-n)<br />
<br />
: Like [[Manual:Lua_Functions#raiseEvent|raiseEvent()]] this raises the event "event_name", but this event is sent to all '''other''' opened profiles instead. The profiles receive the event in circular alphabetical order (if profile "C" raised this event and we have profiles "A", "C", and "E", the order is "E" -> "A", but if "E" raised the event the order would be "A" -> "C"); execution control is handed to the receiving profiles so that means that long running events may lock up the profile that raised the event.<br />
<br />
: The sending profile's name is automatically appended as the last argument to the event.<br />
<br />
{{note}} possible arguments can be string, number, boolean, or nil, but not table or function.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- from profile called "My game" this raises an event "my event" with additional arguments 1, 2, 3, "My game" to all profiles except the original one<br />
raiseGlobalEvent("my event", 1, 2, 3)<br />
<br />
-- want the current profile to receive it as well? Use raiseEvent<br />
raiseEvent("my event", 1, 2, 3)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua><br />
-- example of calling functions in one profile from another:<br />
-- profile B:<br />
control = control or {}<br />
function control.updateStatus()<br />
disableTrigger("test triggers")<br />
print("disabling triggers worked!")<br />
end<br />
<br />
-- this handles calling the right function in the control table<br />
function control.marshaller(_, callfunction)<br />
if control[callfunction] then control[callfunction]()<br />
else<br />
cecho("<red>Asked to call an unknown function: "..callfunction)<br />
end<br />
end<br />
<br />
registerAnonymousEventHandler("sysSendAllProfiles", "control.marshaller")<br />
<br />
-- profile A:<br />
raiseGlobalEvent("sysSendAllProfiles", "updateStatus")<br />
raiseGlobalEvent("sysSendAllProfiles", "invalidfunction")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.1.0}}<br />
<br />
Tip: you might want to add the [[Manual:Miscellaneous_Functions#getProfileName|profile name]] to your plain [[Manual:Miscellaneous_Functions#raiseEvent|raiseEvent()]] arguments. This'll help you tell which profile your event came from similar to [[#raiseGlobalEvent|raiseGlobalEvent()]].<br />
<br />
==registerNamedTimer==<br />
; success = registerNamedTimer(userName, timerName, time, functionReference, [repeating])<br />
<br />
:Registers a named timer with name timerName. Named timers are protected from duplication and can be stopped and resumed, unlike normal tempTimers. A separate list is kept for each userName, to enforce name spacing and avoid collisions<br />
<br />
;See also: [[Manual:Lua_Functions#tempTimer|tempTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]], [[Manual:Lua_Functions#deleteNamedTimer|deleteNamedTimer()]], [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''timerName:''<br />
: The name of the handler. Used to reference the handler in other functions and prevent duplicates. Recommended you use descriptive names, "hp" is likely to collide with something else, "DemonVitals" less so.<br />
* ''time:''<br />
: The amount of time in seconds to wait before firing.<br />
* ''functionReference:''<br />
: The function reference to run when the event comes in. Can be the name of a function, "handlerFunction", or the lua function itself.<br />
* ''repeating:''<br />
: (optional) if true, the timer continue to fire until the stop it using [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
;Returns <br />
* true if successful, otherwise errors.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- establish a named timer called "Check balance" which runs balanceChecker() after 1 second<br />
-- it is started automatically when registered, and fires only once despite being run twice<br />
-- you wouldn't do this intentionally, but illustrates the duplicate protection<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
<br />
-- then the next time you want to make/use the same timer, you can shortcut it with<br />
resumeNamedTimer("Demonnic", "Check Balance")<br />
</syntaxhighlight><br />
<br />
==remainingTime==<br />
;remainingTime(timer id number or name)<br />
<br />
: Returns the remaining time in floating point form in seconds (if it is active) for the timer (temporary or permanent) with the id number or the (first) one found with the name.<br />
: If the timer is inactive or has expired or is not found it will return a ''nil'' and an ''error message''. It, theoretically could also return 0 if the timer is overdue, i.e. it has expired but the internal code has not yet been run but that has not been seen in during testing. Permanent ''offset timers'' will only show as active during the period when they are running after their parent has expired and started them.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
tid = tempTimer(600, [[echo("\nYour ten minutes are up.\n")]])<br />
echo("\nYou have " .. remainingTime(tid) .. " seconds left, use it wisely... \n")<br />
<br />
-- Will produce something like:<br />
<br />
You have 599.923 seconds left, use it wisely... <br />
<br />
-- Then ten minutes time later:<br />
<br />
Your ten minutes are up.<br />
<br />
</syntaxhighlight><br />
<br />
==resetProfileIcon==<br />
;resetProfileIcon()<br />
: Resets the profile's icon in the connection screen to default.<br />
<br />
See also: [[#setProfileIcon|setProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
resetProfileIcon()<br />
</syntaxhighlight><br />
<br />
==resetStopWatch==<br />
;resetStopWatch(watchID)<br />
:This function resets the time to 0:0:0.0, but does not stop or start the stop watch. You can stop it with [[Manual:Lua_Functions#stopStopWatch | stopStopWatch]] or start it with [[Manual:Lua_Functions#startStopWatch | startStopWatch]] → [[Manual:Lua_Functions#createStopWatch | createStopWatch]]<br />
<br />
==resumeNamedTimer==<br />
; success = resumeNamedTimer(userName, handlerName)<br />
<br />
:Resumes a named timer with name handlerName and causes it to fire again. One time unless it was registered as repeating.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameter<br />
* ''userName:''<br />
: The user name the event handler was registered under.s<br />
* ''handlerName:''<br />
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist. If the timer is waiting to fire it will be restarted at 0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local resumed = resumeNamedTimer("Demonnic", "DemonVitals")<br />
if resumed then<br />
cecho("DemonVitals resumed!")<br />
else<br />
cecho("DemonVitals doesn't exist, so cannot resume it.")<br />
end<br />
</syntaxhighlight><br />
<br />
==setButtonState==<br />
;setButtonState(ButtonNameOrID, checked)<br />
:Sets the state of a check-able ("push-down") type button from any Mudlet item's script - but does not cause the script or one of the commands associated with that button to be run/sent.<br />
: See also: [[#getButtonState|getButtonState()]].<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: The name of the button as a string or a unique ID (positive) integer number {for a name only one matching one will be affected - it will be the same one that the matching [[#getButtonState|getButtonState()]] reports upon}.<br />
* ''checked:''<br />
: boolean value that indicated whether the state required is down (''true'') or up (''false''). <br />
<br />
;Returns:<br />
* A boolean value indicating ''true'' if the visible state was actually changed, i.e. had any effect. This function will return a ''nil'' and a suitable error message if the identifying name or ID was not found or was not a check-able (push-down) button item (i.e. was a non-checkable button or a menu or a toolbar instead).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inside, for example, an initialization script for a GUI package:<br />
setButtonState("Sleep", false)<br />
setButtonState("Sit", false)<br />
-- these are going to be used as "radio" buttons where setting one<br />
-- of them will unset all the others, they will each need something<br />
-- similar in their own scripts to unset all the others in the set<br />
-- and also something to prevent them from being unset by clicking<br />
-- on themselves:<br />
setButtonState("Wimpy", true)<br />
setButtonState("Defensive", false)<br />
setButtonState("Normal", false)<br />
setButtonState("Brave", false)<br />
if character.type == "Warrior" then<br />
-- Only one type has this mode - and it can only be reset by<br />
-- something dying (though that could be us!)<br />
setButtonState("Beserk!!!", false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setConsoleBufferSize==<br />
;setConsoleBufferSize([consoleName], linesLimit, sizeOfBatchDeletion)<br />
:Sets the maximum number of lines a buffer (main window or a miniconsole) can hold. Default is 10,000.<br />
:Returns nothing on success (up to '''Mudlet 4.16''') or ''true'' (from '''Mudlet 4.17'''); ''nil'' and an error message on failure.<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
* ''linesLimit:''<br />
: Sets the amount of lines the buffer should have. <br />
{{note}} Mudlet performs extremely efficiently with even huge numbers, but there is of course a limit to your computer's memory. As of Mudlet 4.7+, this amount will be capped to that limit on macOS and Linux (on Windows, it's capped lower as Mudlet on Windows is 32bit).<br />
* ''sizeOfBatchDeletion:''<br />
: Specifies how many lines should Mudlet delete at once when you go over the limit - it does it in bulk because it's efficient to do so.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main windows size to 1 million lines maximum - which is more than enough!<br />
setConsoleBufferSize("main", 1000000, 1000)<br />
</syntaxhighlight><br />
<br />
==setProfileIcon==<br />
;setProfileIcon(iconPath)<br />
:Set a custom icon for this profile in the connection screen. <br />
<br />
:Returns true if successful, or nil+error message if not.<br />
<br />
:See also: [[#resetProfileIcon|resetProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Parameters<br />
* ''iconPath:''<br />
: Full location of the icon - can be .png or .jpg with ideal dimensions of 120x30.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set a custom icon that is located in an installed package called "mypackage"<br />
setProfileIcon(getMudletHomeDir().."/mypackage/icon.png")<br />
</syntaxhighlight><br />
<br />
==setScript==<br />
;setScript(scriptName, luaCode, [occurrence])<br />
: Sets the script's Lua code, replacing existing code. If you have many scripts with the same name, use the 'occurrence' parameter to choose between them.<br />
: If you'd like to add code instead of replacing it, have a look at [[Manual:Lua_Functions#appendScript|appendScript()]].<br />
: Returns -1 if the script isn't found - to create a script, use [[Manual:Lua_Functions#permScript|permScript()]].<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script to change the code.<br />
* ''luaCode'': new Lua code to set.<br />
* ''occurrence'': The position of the script. Optional, defaults to 1 (first).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make sure a script named "testscript" exists first, then do:<br />
setScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
{{MudletVersion|4.8}}<br />
<br />
==setStopWatchName==<br />
;setStopWatchName(watchID/currentStopWatchName, newStopWatchName)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''currentStopWatchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function at that time, or previously applied with this function.<br />
* ''newStopWatchName'' (string): The name to use for this stopwatch from now on.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
{{note}} Either ''currentStopWatchName'' or ''newStopWatchName'' may be empty strings: if the first of these is so then the ''lowest'' ID numbered stopwatch without a name is chosen; if the second is so then an existing name is removed from the chosen stopwatch.<br />
<br />
==setStopWatchPersistence==<br />
;setStopWatchPersistence(watchID/watchName, state)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function or applied later with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]]<br />
* ''state'' (boolean): if ''true'' the stopWatch will be saved.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
:Sets or resets the flag so that the stopwatch is saved between sessions or after a [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] call. If set then, if ''stopped'' the elapsed time recorded will be unchanged when the stopwatch is reloaded in the next session; if ''running'' the elapsed time will continue to increment and it will include the time that the profile was not loaded, therefore it can be used to measure events in real-time, outside of the profile!<br />
<br />
{{note}} When a persistent stopwatch is reloaded in a later session (or after a use of ''resetProfile()'') the stopwatch may not be allocated the same ID number as before - therefore it is advisable to assign any persistent stopwatches a name, either when it is created or before the session is ended.<br />
<br />
==setTriggerStayOpen==<br />
;setTriggerStayOpen(name, number of lines)<br />
:Sets for how many more lines a trigger script should fire or a chain should stay open after the trigger has matched - so this allows you to extend or shorten the ''fire length'' of a trigger. The main use of this function is to close a chain when a certain condition has been met.<br />
<br />
;Parameters<br />
* ''name:'' The name of the trigger which has a fire length set (and which opens the chain).<br />
* ''number of lines'': 0 to close the chain, or a positive number to keep the chain open that much longer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if you have a trigger that opens a chain (has some fire length) and you'd like it to be closed <br />
-- on the next prompt, you could make a prompt trigger inside the chain with a script of:<br />
setTriggerStayOpen("Parent trigger name", 0)<br />
-- to close it on the prompt!<br />
</syntaxhighlight><br />
<br />
==startStopWatch==<br />
;startStopWatch(watchName or watchID, [resetAndRestart])<br />
<br />
:Stopwatches can be stopped (with [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]) and then re-started any number of times. '''To ensure backwards compatibility, if the stopwatch is identified by a ''numeric'' argument then, ''unless a second argument of false is supplied as well'' this function will also reset the stopwatch to zero and restart it - whether it is running or not'''; otherwise only a stopped watch can be started and only a started watch may be stopped. Trying to repeat either will produce a nil and an error message instead; also the recorded time is no longer reset so that they can now be used to record a total of isolated periods of time like a real stopwatch.<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID''/''watchName'': The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], or from '''4.4.0''' the name assigned with that function or [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* ''resetAndRestart'': Boolean flag needed (as ''false'') to make the function from '''4.4.0''', when supplied with a numeric watch ID, to '''not''' reset the stopwatch and only start a previously stopped stopwatch. This behavior is automatic when a string watch name is used to identify the stopwatch but differs from how the function behaved prior to that version.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found or if it cannot be started (because the later style behavior was indicated and it was already running).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches prior to 4.4.0 and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
</syntaxhighlight><br />
<br />
:: After 4.4.0 the above code will work the same as it does not provide a second argument to the ''startStopWatch()'' function - if a ''false'' was used there it would be necessary to call ''stopStopWatch(...)'' and then ''resetStopWatch(...)'' before using ''startStopWatch(...)'' to re-use the stopwatch if the ID form is used, '''this is thus not quite the same behavior but it is more consistent with the model of how a real stopwatch would act.'''<br />
<br />
==stopAllNamedTimers==<br />
; stopAllNamedTimers(userName)<br />
<br />
:Stops all named timers for userName and prevents them from firing any more. Information is retained and timers can be resumed.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
stopAllNamedTimers("Demonnic") -- emergency stop situation, most likely.<br />
</syntaxhighlight><br />
<br />
==stopNamedTimer==<br />
; success = stopNamedTimer(userName, handlerName)<br />
<br />
:Stops a named timer with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist or was already stopped<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local stopped = stopNamedTimer("Demonnic", "DemonVitals")<br />
if stopped then<br />
cecho("DemonVitals stopped!")<br />
else<br />
cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")<br />
end<br />
</syntaxhighlight><br />
<br />
==stopStopWatch==<br />
;stopStopWatch(watchID or watchName)<br />
:"Stops" (though see the note below) the stop watch and returns (only the '''first''' time it is called after the stopwatch has been set running with [[Manual:Lua_Functions#startStopWatch()|startStopWatchTime()]]) the elapsed time as a number of seconds, with a decimal portion give a resolution in milliseconds (thousandths of a second). You can also retrieve the current time without stopping the stopwatch with [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]], [[Manual:Lua_Functions#getBrokenDownStopWatchTime|getBrokenDownStopWatchTime()]].<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID:'' The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or from Mudlet '''4.4.0''' the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns<br />
* the elapsed time as a floating-point number of seconds - it may be negative if the time was previously adjusted/preset to a negative amount (with [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]]) and that period has not yet elapsed.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
<br />
-- do some long-running code here ...<br />
<br />
print("The code took: "..stopStopWatch(watch).."s to run.")<br />
</syntaxhighlight><br />
<br />
==tempAnsiColorTrigger==<br />
;tempAnsiColorTrigger(foregroundColor[, backgroundColor], code[, expireAfter])<br />
:This is an alternative to [[Manual:Lua_Functions#tempColorTrigger|tempColorTrigger()]] which supports the full set of 256 ANSI color codes directly and makes a color trigger that triggers on the specified foreground and background color. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on.<br />
* ''backgroundColor'': The background color you'd like to trigger on.<br />
* ''code to do'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
''BackgroundColor'' and/or ''expireAfter'' may be omitted.<br />
<br />
;Color codes (note that the values greater than or equal to zero are the actual number codes that ANSI and the game server uses for the 8/16/256 color modes)<br />
<br />
::Special codes (may be extended in the future):<br />
:::-2 = default text color (what is used after an ANSI SGR 0 m code that resets the foreground and background colors to those set in the preferences)<br />
:::-1 = ignore (only '''one''' of the foreground or background codes can have this value - otherwise it would not be a ''color'' trigger!)<br />
<br />
::ANSI 8-color set:<br />
:::0 = (dark) black<br />
:::1 = (dark) red<br />
:::2 = (dark) green<br />
:::3 = (dark) yellow<br />
:::4 = (dark) blue<br />
:::5 = (dark) magenta<br />
:::6 = (dark) cyan<br />
:::7 = (dark) white {a.k.a. light gray}<br />
<br />
::Additional colors in 16-color set:<br />
:::8 = light black {a.k.a. dark gray}<br />
:::9 = light red<br />
:::10 = light green<br />
:::11 = light yellow<br />
:::12 = light blue<br />
:::13 = light magenta<br />
:::14 = light cyan<br />
:::15 = light white<br />
<br />
::6 x 6 x 6 RGB (216) colors, shown as a 3x2-digit hex code<br />
:::16 = #000000<br />
:::17 = #000033<br />
:::18 = #000066<br />
:::...<br />
:::229 = #FFFF99<br />
:::230 = #FFFFCC<br />
:::231 = #FFFFFF<br />
<br />
::24 gray-scale, also show as a 3x2-digit hex code<br />
:::232 = #000000<br />
:::233 = #0A0A0A<br />
:::234 = #151515<br />
:::...<br />
:::253 = #E9E9E9<br />
:::254 = #F4F4F4<br />
:::255 = #FFFFFF<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in a light cyan foreground color on any background with a red foreground color<br />
-- until another foreground color in the current line is being met. temporary color triggers do not offer match_all<br />
-- or filter options like the GUI color triggers because this is rarely necessary for scripting.<br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempAnsiColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]])<br />
-- or:<br />
tempAnsiColorTrigger(14, -1, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]], 4)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==tempAlias==<br />
;aliasID = tempAlias(regex, code to do)<br />
:Creates a temporary alias - temporary in the sense that it won't be saved when Mudlet restarts (unless you re-create it). The alias will go off as many times as it matches, it is not a one-shot alias. The function returns an ID for subsequent [[Manual:Lua_Functions#enableAlias|enableAlias()]], [[Manual:Lua_Functions#disableAlias|disableAlias()]] and [[Manual:Lua_Functions#killAlias|killAlias()]] calls.<br />
<br />
;Parameters<br />
* ''regex:'' Alias pattern in regex.<br />
* ''code to do:'' The code to do when the alias fires - wrap it in [[ ]].<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
myaliasID = tempAlias("^hi$", [[send ("hi") echo ("we said hi!")]])<br />
<br />
-- you can also delete the alias later with:<br />
killAlias(myaliasID)<br />
<br />
-- tempAlias also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for an alias look less messy:<br />
<br />
local variable = matches[2]<br />
tempAlias("^hi$", function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempBeginOfLineTrigger==<br />
;tempBeginOfLineTrigger(part of line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the part of line it's provided with matches the line right from the start (doesn't matter what the line ends with). The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''part of line'': start of the line that you'd like to match. This can also be regex.<br />
* ''code to do'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempBeginOfLineTrigger("Hello", [[echo("We matched!")]])<br />
<br />
--[[ now this trigger will match on any of these lines:<br />
Hello<br />
Hello!<br />
Hello, Bob!<br />
<br />
but not on:<br />
Oh, Hello<br />
Oh, Hello!<br />
]]<br />
<br />
-- or as a function:<br />
mytriggerID = tempBeginOfLineTrigger("Hello", function() echo("We matched!") end)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can make the trigger match only a certain amount of times as well, 5 in this example:<br />
tempBeginOfLineTrigger("This is the start of the line", function() echo("We matched!") end, 5)<br />
<br />
-- if you want a trigger match not to count towards expiration, return true. In this example it'll match 5 times unless the line is "Start of line and this is the end."<br />
tempBeginOfLineTrigger("Start of line", <br />
function()<br />
if line == "Start of line and this is the end." then<br />
return true<br />
else<br />
return false<br />
end<br />
end, 5)<br />
</syntaxhighlight><br />
<br />
==tempButton==<br />
;tempButton(toolbar name, button text, orientation)<br />
:Creates a temporary button. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''toolbar name'': The name of the toolbar to place the button into.<br />
* ''button text'': The text to display on the button.<br />
* ''orientation'': a number 0 or 1 where 0 means horizontal orientation for the button and 1 means vertical orientation for the button. This becomes important when you want to have more than one button in the same toolbar.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
{{note}} ''This function is not that useful as there is no function yet to assign a Lua script or command to such a temporary button - though it may have some use to flag a status indication!''<br />
<br />
==tempButtonToolbar==<br />
;tempButtonToolbar(name, location, orientation)<br />
:Creates a temporary button toolbar. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''name'': The name of the toolbar.<br />
* ''location'': a number from 0 to 3, where 0 means "at the top of the screen", 1 means "left side", 2 means "right side" and 3 means "in a window of its own" which can be dragged and attached to the main Mudlet window if needed.<br />
* ''orientation'': a number 0 or 1, where 0 means horizontal orientation for the toolbar and 1 means vertical orientation for the toolbar. This becomes important when you want to have more than one toolbar in the same location of the window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
==tempColorTrigger==<br />
;tempColorTrigger(foregroundColor, backgroundColor, code, expireAfter)<br />
:Makes a color trigger that triggers on the specified foreground and background color. Both colors need to be supplied in form of these simplified ANSI 16 color mode codes. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
See also: [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on (for ANSI colors, see [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]).<br />
* ''backgroundColor'': The background color you'd like to trigger on (same as above).<br />
* ''code to do'': The code to do when the trigger runs - wrap it in <code>[[</code> and <code>]]</code>, or give it a Lua function, ie. <code>function() <nowiki><your code here></nowiki> end</code> (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Color codes<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in blue foreground colors on a black background with a red foreground color<br />
-- on a blue background color until another color in the current line is being met. temporary color triggers do not <br />
-- offer match_all or filter options like the GUI color triggers because this is rarely necessary for scripting. <br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]])<br />
-- or:<br />
tempColorTrigger(9, 2, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
bg("blue")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]], 4)<br />
</syntaxhighlight><br />
<br />
==tempComplexRegexTrigger==<br />
;tempComplexRegexTrigger(name, regex, code, multiline, fg color, bg color, filter, match all, highlight fg color, highlight bg color, play sound file, fire length, line delta, expireAfter)<br />
:Allows you to create a temporary trigger in Mudlet, using any of the UI-available options. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
:Returns the trigger name, that you can use [[Manual:Lua_Functions#killTrigger|killTrigger()]] later on with.<br />
<br />
;Parameters<br />
* ''name'' - The name you call this trigger. <br />
* ''regex'' - The regular expression you want to match.<br />
* ''code'' - Code to do when the trigger runs. You need to wrap it in [[ ]], or give a Lua function (since Mudlet 3.5.0).<br />
* ''multiline'' - Set this to 1, if you use multiple regex (see note below), and you need the trigger to fire only if all regex have been matched within the specified line delta. Then all captures will be saved in ''multimatches'' instead of ''matches''. If this option is set to 0, the trigger will fire when any regex has been matched.<br />
* ''fg color'' - The foreground color you'd like to trigger on.<br />
* ''bg color'' - The background color you'd like to trigger on.<br />
* ''filter'' - Do you want only the filtered content (=capture groups) to be passed on to child triggers? Otherwise also the initial line.<br />
* ''match all'' - Set to 1, if you want the trigger to match all possible occurrences of the regex in the line. When set to 0, the trigger will stop after the first successful match.<br />
* ''highlight fg color'' - The foreground color you'd like your match to be highlighted in.<br />
* ''highlight bg color'' - The background color you'd like your match to be highlighted in.<br />
* ''play sound file'' - Set to the name of the sound file you want to play upon firing the trigger.<br />
* ''fire length'' - Number of lines within which all condition must be true to fire the trigger.<br />
* ''line delta'' - Keep firing the script for x more lines, after the trigger or chain has matched.<br />
* ''expireAfter'' - Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
{{Note}} Set the options starting at ''multiline'' to 0, if you don't want to use those options. Otherwise enter 1 to activate or the value you want to use.<br />
<br />
{{Note}} If you want to use the color option, you need to provide both fg and bg together.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- This trigger will be activated on any new line received.<br />
triggerNumber = tempComplexRegexTrigger("anyText", "^(.*)$", [[echo("Text received!")]], 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
<br />
-- This trigger will match two different regex patterns:<br />
tempComplexRegexTrigger("multiTrigger", "first regex pattern", [[]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
tempComplexRegexTrigger("multiTrigger", "second regex pattern", [[echo("Trigger matched!")]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
</syntaxhighlight><br />
<br />
{{Note}} For making a multiline trigger like in the second example, you need to use the same trigger name and options, providing the new pattern to add. Note that only the last script given will be set, any others ignored.<br />
<br />
==tempExactMatchTrigger==<br />
;tempExactMatchTrigger(exact line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the line from the game matches the provided line exactly (ends the same, starts the same, and looks the same). You don't need to use any of the regex symbols here (^ and $). The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''exact line'': exact line you'd like to match.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", [[echo("We matched!")]])<br />
<br />
-- as a function:<br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("We matched!") end)<br />
<br />
-- expire after 4 matches:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") end, 4)<br />
<br />
-- you can also avoid expiration by returning true:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") return true end, 4)<br />
</syntaxhighlight><br />
<br />
==tempKey==<br />
;tempKey([modifier], key code, lua code)<br />
:Creates a keybinding. This keybinding isn't temporary in the sense that it'll go off only once (it'll go off as often as you use it), but rather it won't be saved when Mudlet is closed.<br />
<br />
: See also: [[#permKey|permKey()]], [[#killKey|killKey()]]<br />
<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
* ''lua code'<br />
: code you'd like the key to run - wrap it in [[ ]].<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
keyID = tempKey(mudlet.key.F8, [[echo("hi")]])<br />
<br />
anotherKeyID = tempKey(mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hello")]])<br />
<br />
-- bind Ctrl+Shift+W:<br />
tempKey(mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
<br />
-- delete it if you don't like it anymore<br />
killKey(keyID)<br />
<br />
-- tempKey also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for tempKeys look less messy:<br />
<br />
tempKey(mudlet.key.F8, function() echo("Hi\n") end)<br />
</syntaxhighlight><br />
<br />
==tempLineTrigger==<br />
;tempLineTrigger(from, howMany, code)<br />
:Temporary trigger that will fire on ''n'' consecutive lines following the current line. This is useful to parse output that is known to arrive in a certain line margin or to delete unwanted output from the game - the trigger does not require any patterns to match on. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''from'': from which line after this one should the trigger activate - 1 will activate right on the next line.<br />
* ''howMany'': how many lines to run for after the trigger has activated.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
-- Will fire 3 times with the next line from the game<br />
tempLineTrigger(1, 3, function() print(" trigger matched!") end)<br />
<br />
-- Will fire 5 lines after the current line and fire twice on 2 consecutive lines<br />
tempLineTrigger(5, 2, function() print(" trigger matched!") end, 7)<br />
</syntaxhighlight><br />
<br />
==tempPromptTrigger==<br />
;tempPromptTrigger(code, expireAfter)<br />
:Temporary trigger that will match on the games prompt. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead to be enabled in the game. <br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Parameters:<br />
* ''code'': <br />
: code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': (available in Mudlet 3.11+)<br />
: Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end)<br />
<br />
-- match only 2 times:<br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end, 2)<br />
<br />
-- match only 2 times, unless the prompt is "55 health."<br />
tempPromptTrigger(function()<br />
if line == "55 health." then return true end<br />
end, 2)<br />
</syntaxhighlight><br />
<br />
==tempRegexTrigger==<br />
;tempRegexTrigger(regex, code, expireAfter)<br />
:Creates a temporary regex trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''regex:'' regular expression that lines will be matched on.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- create a non-duplicate trigger that matches on any line and calls a function<br />
html5log = html5log or {}<br />
if html5log.trig then killTrigger(html5log.trig) end<br />
html5log.trig = tempRegexTrigger("^", [[html5log.recordline()]])<br />
-- or a simpler variant:<br />
html5log.trig = tempRegexTrigger("^", html5log.recordline)<br />
<br />
-- only match 3 times:<br />
tempRegexTrigger("^You prick (.+) twice in rapid succession with", function() echo("Hit "..matches[2].."!\n") end, 3)<br />
<br />
-- since Mudlet 4.11+ you can use named capturing groups<br />
tempRegexTrigger("^You see (?<material>\\w+) axe inside chest\\.", function() echo("\nAxe is " .. matches.material) end)<br />
</syntaxhighlight><br />
<br />
==tempTimer==<br />
;tempTimer(time, code to do[, repeating])<br />
:Creates a temporary one-shot timer and returns the timer ID, which you can use with [[Manual:Lua_Functions#enableTimer|enableTimer()]], [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#killTimer|killTimer()]] functions. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and destroyed, so it will only go off once. Here is a [[Manual:Introduction#Timers|more detailed introduction to tempTimer]].<br />
<br />
;Parameters<br />
* ''time:'' The time in seconds for which to set the timer for - you can use decimals here for precision. The timer will go off ''x'' given seconds after you make it.<br />
* ''code to do'': The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.<br />
* ''repeating'': (optional) if true, keep firing the timer over and over until you kill it (available in Mudlet 4.0+).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- wait half a second and then run the command<br />
tempTimer(0.5, function() send("kill monster") end)<br />
<br />
-- echo between 1 and 5 seconds after creation<br />
tempTimer(math.random(1, 5), function() echo("hi!") end) <br />
<br />
-- or an another example - two ways to 'embed' variable in a code for later:<br />
local name = matches[2]<br />
tempTimer(2, [[send("hello, ]]..name..[[ !")]])<br />
-- or:<br />
tempTimer(2, function()<br />
send("hello, "..name)<br />
end)<br />
<br />
-- create a looping timer<br />
timerid = tempTimer(1, function() display("hello!") end, true)<br />
<br />
-- later when you'd like to stop it:<br />
killTimer(timerid)<br />
</syntaxhighlight><br />
<br />
{{note}} Double brackets, e.g: [[ ]] can be used to quote strings in Lua. The difference to the usual `" " quote syntax is that `[[ ]] also accepts the character ". Consequently, you don’t have to escape the " character in the above script. The other advantage is that it can be used as a multiline quote, so your script can span several lines.<br />
<br />
{{note}} Lua code that you provide as an argument is compiled from a string value when the timer fires. This means that if you want to pass any parameters by value e.g. you want to make a function call that uses the value of your variable myGold as a parameter you have to do things like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
tempTimer( 3.8, [[echo("at the time of the tempTimer call I had ]] .. myGold .. [[ gold.")]] )<br />
<br />
-- tempTimer also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for timers look less messy:<br />
<br />
local variable = matches[2]<br />
tempTimer(3, function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempTrigger==<br />
;tempTrigger(substring, code, expireAfter)<br />
:Creates a substring trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''substring'': The substring to look for - this means a part of the line. If your provided text matches anywhere within the line from the game, the trigger will go off.<br />
* ''code'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5)<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
-- this example will highlight the contents of the "target" variable.<br />
-- it will also delete the previous trigger it made when you call it again, so you're only ever highlighting one name<br />
if id then killTrigger(id) end<br />
id = tempTrigger(target, [[selectString("]] .. target .. [[", 1) fg("gold") resetFormat()]])<br />
<br />
-- you can also write the same line as:<br />
id = tempTrigger(target, function() selectString(target, 1) fg("gold") resetFormat() end)<br />
<br />
-- or like so if you have a highlightTarget() function somewhere<br />
id = tempTrigger(target, highlightTarget)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a simpler trigger to replace "hi" with "bye" whenever you see it<br />
tempTrigger("hi", [[selectString("hi", 1) replace("bye")]])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this trigger will go off only 2 times<br />
tempTrigger("hi", function() selectString("hi", 1) replace("bye") end, 2)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- table to store our trigger IDs in<br />
nameIDs = nameIDs or {}<br />
-- delete any existing triggers we've already got<br />
for _, id in ipairs(nameIDs) do killTrigger(id) end<br />
<br />
-- create new ones, avoiding lots of ]] [[ to embed the name<br />
for _, name in ipairs{"Alice", "Ashley", "Aaron"} do<br />
nameIDs[#nameIDs+1] = tempTrigger(name, function() print(" Found "..name.."!") end)<br />
end<br />
</syntaxhighlight><br />
<br />
;Additional Notes:<br />
tempTriggers begin matching on the same line they're created on. <br />
<br />
If your ''code'' deletes and recreates the tempTrigger, or if you ''send'' a matching command again, it's possible to get into an infinite loop.<br />
<br />
Make use of the ''expireAfter'' parameter, [[Manual:Lua_Functions#disableTrigger|disableTrigger()]], or [[Manual:Lua_Functions#killTrigger|killTrigger()]] to prevent a loop from forming.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Vadihttps://wiki.mudlet.org/index.php?title=Infrastructure_Overview&diff=20443Infrastructure Overview2023-05-02T17:16:22Z<p>Vadi: Added PTBs</p>
<hr />
<div>* various [[Github Actions]] (linux + macos builds and various infrastructure helpers)<br />
*[[Github Actions|appveyor windows builds]]<br />
* [https://github.com/Mudlet/deployment-link-probot deployment links probot]<br />
*[https://github.com/Mudlet/ci-snapshots snapshots website] (deployed [https://make.mudlet.org/snapshots here])<br />
*[https://danger.systems/js DangerJS] for automated PR checks ([https://github.com/Mudlet/Mudlet/blob/development/.github/workflows/dangerjs.yml workflow], [https://github.com/Mudlet/Mudlet/blob/development/dangerfile.js checks])<br />
* this [https://www.mediawiki.org/wiki/MediaWiki mediawiki] site<br />
**[[Wiki Translation Infrastructure|translation infrastructure]]<br />
*[https://www.mudlet.org/ mudlet.org] wordpress site<br />
**[https://github.com/Mudlet/mudlet-release-plugin plugin] to syncronise github releases with mudlet.org<br />
*[https://forums.mudlet.org/ forums.mudlet.org] phpbb forums<br />
*[[Rainforest Testing|Rainforest QA]] for testing Mudlet visually<br />
* C++ ([https://doc.qt.io/qt-5/qtest-overview.html Qt Test]) automated tests ([https://github.com/Mudlet/Mudlet/tree/development/test github])<br />
* Lua ([http://olivinelabs.com/busted/ Busted]) automated tests ([https://github.com/Mudlet/Mudlet/tree/development/src/mudlet-lua github])<br />
* Performance tests (for measuring display speed) on a Raspberry Pi ([https://github.com/Mudlet/Mudlet/blob/development/.github/workflows/performance-analysis.yml performance-analysis.yml])<br />
** Chart [https://docs.google.com/spreadsheets/d/e/2PACX-1vT8yUIGjORyCD284ItcfHXprduAnCBGpJbPRKC-3uSkzY6JK2TOPJ17Rfibi8nh9VWdCxHCjlItnBhq/pubchart?oid=1268116248&format=interactive available here]<br />
* [[Public Test Builds]]<br />
*[[China Mirrors]]<br />
*[https://docs.smoogle.gg/ Smoogle] translation bot for discord<br />
*[[Answeroverflow]] for exposing #help and #help-international to search engines<br />
*[[pmalerts]] for notifying #mudlet-pulse of project mentions on the web<br />
*[https://zapier.com zapier] for posting wiki edits to #mudlet-pulse</div>Vadihttps://wiki.mudlet.org/index.php?title=File:PTB_creation.svg&diff=20442File:PTB creation.svg2023-05-02T17:15:23Z<p>Vadi: Vadi uploaded a new version of File:PTB creation.svg</p>
<hr />
<div>Process to create PTBs</div>Vadihttps://wiki.mudlet.org/index.php?title=Public_Test_Builds&diff=20441Public Test Builds2023-05-02T17:14:03Z<p>Vadi: </p>
<hr />
<div>= Public Test Builds =<br />
<br />
PTB's (public test builds) are daily updates of the latest Mudlet code, available at [https://mudlet.org/ptb mudlet.org/ptb]. They can be downloaded and used directly next to your regular Mudlet version, so you can always switch back! Please let us know any questions or doubts you find while using a PTB - they are intended as a way to preview new improvements/changes before official releases.<br />
<br />
== Developer information ==<br />
<br />
==== PTB creation ====<br />
To create the PTB, the Windows CI build on [https://ci.appveyor.com/project/Mudlet/mudlet Appveyor] runs daily at 1am UTC, builds the Windows PTB Mudlet and uploads it to the Mudlet server. It then generates a changelog delta to the previous PTB, creates a new PTB release in dblsqd with the said changelog, and attaches the Windows PTB to the dblsqd release. Windows builds run first since the range of Appveyor IP's is rather limited and we are able to whitelist them - enabling direct uploads from the build.<br />
<br />
Then, macOS and Linux builds run on [https://github.com/Mudlet/Mudlet/blob/37dfdf26d0e5692f9f3ff6bdcdf8c108b9db8a2a/.github/workflows/build-mudlet.yml#L9 Github] at 2am UTC, build macOS/Linux PTBs, save them as artifacts in the workflow, and notify the Mudlet server. Direct uploading is not possible since the range of Github Actions IP's is the entire Microsoft Azure cloud, and whitelisting those IPs is not practical. Mudlet server, upon being notified by the build job, then downloads the macOS/Linux PTBs from the job artifacts. At 3pm UTC, having given the build & upload enough time to complete, a [https://github.com/Mudlet/Mudlet/blob/37dfdf26d0e5692f9f3ff6bdcdf8c108b9db8a2a/.github/workflows/link-ptbs-to-dblsqd.yml#L6 Github action] attaches the macos/Linux PTBs to the same dblsqd release.<br />
[[File:PTB creation.svg|center|frame]]<br />
Unrelated to all of this, a [https://github.com/Mudlet/Mudlet/blob/development/.github/workflows/generate-changelog.yml changelog generation] action is available to create a changelog for Discord/Wordpress on demand.<br />
<br />
==== Updating to a PTB ====<br />
To update to a PTB, Mudlet checks for updates every 12h to see if any are available on the server. If there are updates available, and auto-update is enabled, then the update is updated in the background and applied when the user closes the application. If auto-update is disabled, a notification is shown to the user when they quit Mudlet that an update is available.<br />
[[File:PTB updates.svg|center|frame]]</div>Vadi