Added a script command for instance information (#1815)

With this script command you can look up information about a specific instance. This way you do not have to hardcode values specified in the database in the script if you need it.

Thanks to @aleos89 for the script documentation.

doc/script_commands.txt

@@ -8389,6 +8389,30 @@ if (instance_check_guild(getcharid(2),2,2,149)) {
 
 ---------------------------------------
 
+*instance_info("<instance name>",<info type>{,<instance_db map index>});
+
+Returns the specified <info type> of the given <instance name> from the instance database.
+If the <instance name> is unknown or an invalid <info type> is supplied -1 will be returned.
+
+Valid info types:
+ IIT_ID: Instance database ID as integer.
+ IIT_TIME_LIMIT: Instance database total life time as integer.
+ IIT_IDLE_TIMEOUT: Instance database timeout time as integer.
+ IIT_ENTER_MAP: Instance database enter map as string.
+ IIT_ENTER_X: Instance database enter X location as integer.
+ IIT_ENTER_Y: Instance database enter Y location as integer.
+ IIT_MAPCOUNT: Instance database total maps as integer.
+ IIT_MAP: Instance database map name from the given <instance_db map index> as string.
+          If the index is invalid an empty string will be returned.
+
+Example:
+
+.@name$ = "Endless Tower";
+mes .@name$ + " will be destroyed if no one is in the instance for " + instance_info(.@name$,IIT_IDLETIMEOUT) + " seconds.";
+// Endless Tower will be destroyed if no one is in the instance for 300 seconds.
+
+---------------------------------------
+
 =========================
 |8.- Quest Log commands.|
 =========================

src/map/instance.c

@@ -50,7 +50,7 @@ static uint16 instance_name2id(const char *instance_name) {
 /*==========================================
  * Searches for an instance name in the database
  *------------------------------------------*/
-static struct instance_db *instance_searchname_db(const char *instance_name) {
+struct instance_db *instance_searchname_db(const char *instance_name) {
 	uint16 id = instance_name2id(instance_name);
 	if (id == 0)
 		return NULL;

src/map/instance.h

@@ -71,6 +71,7 @@ extern int instance_start;
 extern struct instance_data instance_data[MAX_INSTANCE_DATA];
 
 struct instance_db *instance_searchtype_db(unsigned short instance_id);
+struct instance_db *instance_searchname_db(const char* name);
 void instance_getsd(unsigned short instance_id, struct map_session_data **sd, enum send_target *target);
 
 int instance_create(int owner_id, const char *name, enum instance_mode mode);

src/map/script.c

@@ -19525,6 +19525,81 @@ BUILDIN_FUNC(instance_check_guild)
 	return SCRIPT_CMD_SUCCESS;
 }
 
+/*==========================================
+* instance_info
+* Values:
+* name : name of the instance you want to look up. [Required Parameter]
+* type : type of information you want to look up for the specified instance. [Required Parameter]
+* index : index of the map in the instance. [Optional Parameter]
+*------------------------------------------*/
+BUILDIN_FUNC(instance_info)
+{
+	const char* name = script_getstr(st, 2);
+	int type = script_getnum(st, 3);
+	int index = 0;
+	struct instance_db *db = instance_searchname_db(name);
+
+	if( !db ){
+		ShowError( "buildin_instance_info: Unknown instance name \"%s\".\n", name );
+		script_pushint(st, -1);
+		return SCRIPT_CMD_FAILURE;
+	}
+
+	switch( type ){
+		case IIT_ID:
+			script_pushint(st, db->id);
+			break;
+		case IIT_TIME_LIMIT:
+			script_pushint(st, db->limit);
+			break;
+		case IIT_IDLE_TIMEOUT:
+			script_pushint(st, db->timeout);
+			break;
+		case IIT_ENTER_MAP:
+			script_pushstrcopy(st, StringBuf_Value(db->enter.mapname));
+			break;
+		case IIT_ENTER_X:
+			script_pushint(st, db->enter.x);
+			break;
+		case IIT_ENTER_Y:
+			script_pushint(st, db->enter.y);
+			break;
+		case IIT_MAPCOUNT:
+			script_pushint(st, db->maplist_count);
+			break;
+		case IIT_MAP:
+			if( !script_hasdata(st, 4) || script_isstring(st, 4) ){
+				ShowError( "buildin_instance_info: Type IIT_MAP requires a numeric index argument.\n" );
+				script_pushstr(st, "");
+				return SCRIPT_CMD_FAILURE;
+			}
+
+			index = script_getnum(st, 4);
+
+			if( index < 0 ){
+				ShowError( "buildin_instance_info: Type IIT_MAP does not support a negative index argument.\n" );
+				script_pushstr(st, "");
+				return SCRIPT_CMD_FAILURE;
+			}
+
+			if( index > UINT8_MAX ){
+				ShowError( "buildin_instance_info: Type IIT_MAP does only support up to index %hu.\n", UINT8_MAX );
+				script_pushstr(st, "");
+				return SCRIPT_CMD_FAILURE;
+			}
+
+			script_pushstrcopy(st, StringBuf_Value(db->maplist[index]));
+			break;
+
+		default:
+			ShowError("buildin_instance_info: Unknown instance information type \"%d\".\n", type );
+			script_pushint(st, -1);
+			return SCRIPT_CMD_FAILURE;
+	}
+
+	return SCRIPT_CMD_SUCCESS;
+}
+
 /*==========================================
  * Custom Fonts
  *------------------------------------------*/
@@ -22612,6 +22687,7 @@ struct script_function buildin_func[] = {
 	BUILDIN_DEF(instance_announce,"isi?????"),
 	BUILDIN_DEF(instance_check_party,"i???"),
 	BUILDIN_DEF(instance_check_guild,"i???"),
+	BUILDIN_DEF(instance_info,"si?"),
 	/**
 	 * 3rd-related
 	 **/

src/map/script.h

@@ -642,6 +642,18 @@ enum random_option_attribute {
 	ROA_VALUE,
 	ROA_PARAM,
 };
+
+enum instance_info_type {
+	IIT_ID,
+	IIT_TIME_LIMIT,
+	IIT_IDLE_TIMEOUT,
+	IIT_ENTER_MAP,
+	IIT_ENTER_X,
+	IIT_ENTER_Y,
+	IIT_MAPCOUNT,
+	IIT_MAP
+};
+
 /**
  * used to generate quick script_array entries
  **/

src/map/script_constants.h

@@ -3204,6 +3204,16 @@
 	export_constant(IE_NOINSTANCE);
 	export_constant(IE_OTHER);
 
+	/* instance info */
+	export_constant(IIT_ID);
+	export_constant(IIT_TIME_LIMIT);
+	export_constant(IIT_IDLE_TIMEOUT);
+	export_constant(IIT_ENTER_MAP);
+	export_constant(IIT_ENTER_X);
+	export_constant(IIT_ENTER_Y);
+	export_constant(IIT_MAPCOUNT);
+	export_constant(IIT_MAP);
+
 	/* item groups */
 	export_constant(IG_BLUEBOX);
 	export_constant(IG_VIOLETBOX);