Add script commands to generate some client <TAGS>

doc/script_commands.txt

@@ -2612,6 +2612,140 @@ deleted.
 	// This would delete all elements of the array
 	deletearray(.@array);
 
+---------------------------------------
+//=====================================
+1.1 - Message formatting commands (tags)
+//=====================================
+---------------------------------------
+
+*mesnavigation("<label>", "<map>"{, <x>{, <y>{, <show_window>{, <mode>{, <services_flag>{, <monster_id>}}}}}});
+
+Generates and returns a <NAVI> tag with the given parameters. A <NAVI> tag when written to certain windows,
+such as the one from "mes" command, will create a highlighted and clickable text, which when clicked,
+starts the navigation system for the specified values.
+
+It is important to note that for most "<modes>" values, it is expected that your client has proper navigation
+files which includes the target NPC/monster, or they will fail.
+
+If the current client doesn't support NAVI tags, returns a fall back text which generally looks like:
+	<label> (<map_name> <x>, <y>)
+
+Parameters:
+- label: (string, required)
+	The visible and clickable text. (example: "Hat maker")
+
+- map: (string, required)
+	Target map name. (example: "prontera")
+	Note: when service_flag is NAV_WINDOW_SEARCH (-222) this becomes the search string.
+
+- x: (int, optional, defaults to 0)
+	Target map X position
+	Note: does nothing when used with modes NAV_MODE_MAP or NAV_MODE_MOB
+
+- y: (int, optional, defaults to 0)
+	Target map Y position
+	Note: does nothing when used with modes NAV_MODE_MAP or NAV_MODE_MOB
+
+- show_window: (bool, optional, defaults to false)
+	Whether to open the navigation UI (true) or not (false) when clicking the label.
+
+- mode: (int, optional, defaults to NAV_MODE_ALL (0))
+	The kind of navigation being performed. This mainly affects the messages shown by the client when you reach the map.
+	- NAV_MODE_ALL (0): "You have reached your destination"
+	- NAV_MODE_MAP (1): "You have reached the target map"
+	- NAV_MODE_NPC (2): "You have reached the map the NPC is at" / "You have reached the target NPC"
+	- NAV_MODE_MOB (3): "You have reached the map where the monster appears"
+
+	Notes:
+	- NAV_MODE_NPC requires client navigation files to have a NPC in the exact position or an error is shown
+	- NAV_MODE_MOB requires client navigation files to have <monster_id> spawn in the given map or an error is shown.
+
+- services_flag: (int, optional, defaults to NAV_KAFRA_AND_AIRSHIP (101))
+	The kinds of services that may be used when calculating the route.
+
+	The following values may be summed up:
+	- NAV_AIRSHIP_ONLY (1): Include airships
+	- NAV_SCROLL_ONLY (10): Include scrolls
+	- NAV_KAFRA_ONLY (100): Include kafras
+
+	Summed values:
+	- NAV_AIRSHIP_AND_SCROLL (11)
+	- NAV_KAFRA_AND_AIRSHIP (101)
+	- NAV_KAFRA_AND_SCROLL (110)
+	- NAV_ALL (111)
+
+	Special values:
+	- NAV_WINDOW_SEARCH (-222)
+		This is a special value that can't be summed with others and when used,
+		"map" becomes a search string in the navigation UI. And client performs a search
+		with the special keyword "$$DB".
+		It is only known to work together with mode = NAV_MODE_MOB and using monster Sprite Name
+		as "map".
+		When using NAV_WINDOW_SEARCH, prefer using mesmobspawn instead.
+
+- monster_id: (int, optional, defaults to 0)
+	To be used with mode = NAV_MODE_MOB. The ID of the monster being looked for.
+
+---------------------------------------
+
+*mesmobspawn(<monster_id>{, "<label>"})
+
+Generates and returns a <NAVI> tag that opens the Navigation UI listing the places where <monster_id> monster spawns.
+
+This will only work if your client navigation files are properly configured with the <monster_id> spawns.
+
+If the current client doesn't support this feature, returns the value of <label>.
+
+Parameters:
+- monster_id: (int, required)
+	The ID of the monster being looked for.
+
+- label: (string, optional, defaults to <monster_id> name)
+	The visible and clickable text. (example: "Target monster")
+
+---------------------------------------
+
+*mesurl("<label>", "url"{, <width>, <height>})
+
+Generates and returns a <URL> tag. When presented in certain places (like with "mes" and "mesf"),
+this will display a clickable text (<label>) which when clicked, opens <url> in the in-game browser
+or default browser (depending on client version).
+
+If the current client doesn't support this feature, returns a basic string in the following format:
+	<label> (<url>)
+
+Parameters:
+- label: (string, required)
+	The visible and clickable text. (example: "My site")
+
+- url: (string, required)
+	The site that will open when <label> is clicked
+
+- width: (int, optional, defaults to -1)
+	The width of the browser window (when using in-game browser).
+	When not provided (or -1), width/height is not specified.
+
+- height: (int, optional, defaults to -1)
+	The height of the browser window (when using in-game browser).
+	When not provided (or -1), width/height is not specified.
+
+---------------------------------------
+
+*mestipbox("<label>", <tip_id>)
+
+Generates and returns a <TIPBOX> tag. When presented in certain places (like with "mes" and "mesf"),
+this will display a clickable text (<label>) which when clicked, opens the TipBox UI with the given <tip_id>.
+
+If the current client doesn't support this feature, returns a simple string with "<label>"
+
+Parameters:
+- label: (string, required)
+	The visible and clickable text. (example: "Super Tip")
+
+- tip_id: (int, required)
+	The tip ID (as set in TipBox lua file)
+	If 0, it shows a random tipbox
+
 ---------------------------------------
 //=====================================
 1 - End of Basic-Related Commands

npc/dev/test.txt

@@ -261,6 +261,113 @@ function	script	F_TestGetItemLink_FullWeapon	{
 	return .@pass;
 }
 
+function	script	F_TestMesNavigation_Basic	{
+	.@str$ = mesnavigation("Somewhere", "prt_fild08", 100, 105);
+
+	.@pass = false;
+	if (PACKETVER < 20111010) {
+		.@pass = (.@str$ == "Somewhere (prt_fild08 100, 105)");
+	} else {
+		.@pass = (.@str$ == "<NAVI>Somewhere<INFO>prt_fild08,100,105,</INFO></NAVI>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesNavigation_Complete	{
+	.@str$ = mesnavigation("Some NPC", "prt_fild08", 175, 370, true, NAV_MODE_ALL, NAV_NONE);
+
+	.@pass = false;
+	if (PACKETVER < 20111010) {
+		.@pass = (.@str$ == "Some NPC (prt_fild08 175, 370)");
+	} else {
+		.@pass = (.@str$ == "<NAVI>Some NPC<INFO>prt_fild08,175,370,0,0,1,0</INFO></NAVI>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesNavigation_Search	{
+	.@str$ = mesnavigation("Some Monster", "PORING", 0, 0, true, NAV_MODE_MOB, NAV_WINDOW_SEARCH);
+
+	.@pass = false;
+	if (PACKETVER < 20130800) {
+		.@pass = (.@str$ == "Some Monster");
+	} else {
+		.@pass = (.@str$ == "<NAVI>Some Monster<INFO>PORING,0,0,3,-222</INFO></NAVI>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesMobSpawn_Basic	{
+	.@str$ = mesmobspawn(PORING);
+
+	.@pass = false;
+	if (PACKETVER < 20130800) {
+		.@pass = (.@str$ == "Poring");
+	} else {
+		.@pass = (.@str$ == "<NAVI>Poring<INFO>PORING,0,0,3,-222</INFO></NAVI>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesMobSpawn_WithLabel	{
+	.@str$ = mesmobspawn(PORING, "Target");
+
+	.@pass = false;
+	if (PACKETVER < 20130800) {
+		.@pass = (.@str$ == "Target");
+	} else {
+		.@pass = (.@str$ == "<NAVI>Target<INFO>PORING,0,0,3,-222</INFO></NAVI>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesUrl_Basic	{
+	.@str$ = mesurl("Herc", "https://herc.ws/");
+
+	.@pass = false;
+	if (PACKETVER < 20111010) {
+		.@pass = (.@str$ == "Herc (URL: https://herc.ws/)");
+	} else {
+		.@pass = (.@str$ == "<URL>Herc<INFO>https://herc.ws/</INFO></URL>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesUrl_Dimensions	{
+	.@str$ = mesurl("Herc", "https://herc.ws/", 800, 600);
+
+	.@pass = false;
+	if (PACKETVER < 20111010) {
+		.@pass = (.@str$ == "Herc (URL: https://herc.ws/)");
+	} else if (PACKETVER < 20181024) {
+		.@pass = (.@str$ == "<URL>Herc<INFO>https://herc.ws/,800,600</INFO></URL>");
+	} else {
+		// dimensions are no longer supported since it now uses users' default browser.
+		.@pass = (.@str$ == "<URL>Herc<INFO>https://herc.ws/</INFO></URL>");
+	}
+
+	return .@pass;
+}
+
+function	script	F_TestMesTipBox	{
+	.@str$ = mestipbox("Some tip", 1);
+
+	.@pass = false;
+	if (PACKETVER < 20170712) {
+		.@pass = (.@str$ == "Some tip");
+	} else {
+		.@pass = (.@str$ == "<TIPBOX>Some tip<INFO>1</INFO></TIPBOX>");
+	}
+
+	return .@pass;
+}
+
 function	script	HerculesSelfTestHelper	{
 	if (.once > 0)
 		return .errors;
@@ -978,6 +1085,18 @@ function	script	HerculesSelfTestHelper	{
 	callsub(OnCheck, "getitemlink: basic weapon tag", F_TestGetItemLink_BaseWeapon(), true);
 	callsub(OnCheck, "getitemlink: complete weapon tag", F_TestGetItemLink_FullWeapon(), true);
 
+	callsub(OnCheck, "mesnavigation: basic destination", F_TestMesNavigation_Basic(), true);
+	callsub(OnCheck, "mesnavigation: all params", F_TestMesNavigation_Complete(), true);
+	callsub(OnCheck, "mesnavigation: monster spawn search", F_TestMesNavigation_Search(), true);
+
+	callsub(OnCheck, "mesmobspawn: basic usage", F_TestMesMobSpawn_Basic(), true);
+	callsub(OnCheck, "mesmobspawn: with label", F_TestMesMobSpawn_WithLabel(), true);
+
+	callsub(OnCheck, "mesurl: basic usage", F_TestMesUrl_Basic(), true);
+	callsub(OnCheck, "mesurl: with dimensions", F_TestMesUrl_Dimensions(), true);
+
+	callsub(OnCheck, "mestipbox", F_TestMesTipBox(), true);
+
 	if (.errors) {
 		consolemes(CONSOLEMES_DEBUG, "Script engine self-test   [ \033[0;31mFAILED\033[0m ]");
 		consolemes(CONSOLEMES_DEBUG, "**** The test was completed with " + .errors + " errors. ****");