Added an additional parameter to instance_enter (#1720)

Added an additional parameter to instance_enter

This allows easier usage for instances in IM_NONE, where a player will never be attached to the instance.
All you have to do is remember the created instance id and supply this command with it. That way you do not have to use any workaround like the following anymore:
warp instance_mapname( <mapname>, <instance id> ), <hardcoded enter x coordinate>, <hardcoded enter y coordinate>;

Added usage of the new constants in the existing scripts

Fixed default checks and null pointer output
Thanks to @Atemo

doc/script_commands.txt

@@ -8276,15 +8276,15 @@ that fails, the script will come to a halt.
 
 ---------------------------------------
 
-*instance_enter("<instance name>",{<x>,<y>,<char_id>});
+*instance_enter("<instance name>",{<x>,<y>,<char_id>,<instance id>});
 
 Warps player to the specified instance after the script terminates. The map and
 coordinates are located in 'db/(pre-)re/instance_db.txt'.
 
-The command returns 0 upon success, and these values upon failure:
- 1: Party/Guild not found (for party/guild modes).
- 2: Character/Party/Guild does not have an instance.
- 3: Other errors (invalid instance name, instance doesn't match with character/party/guild).
+The command returns IE_OK upon success, and these values upon failure:
+ IE_NOMEMBER:	Party/Guild not found (for party/guild modes).
+ IE_NOINSTANCE:	Character/Party/Guild does not have an instance.
+ IE_OTHER:		Other errors (invalid instance name, instance doesn't match with character/party/guild).
 
 Put -1 for x and y if want to warp player with default entrance coordinates.
 

npc/instances/EndlessTower.txt

@@ -294,17 +294,17 @@ e_tower,81,105,0	script	Tower Protection Stone	406,{
 
 L_Enter:
 	switch(instance_enter("Endless Tower")) {
-	case 3:
+	case IE_OTHER:
 		mes "An unknown error has occurred.";
 		close;
-	case 2:
+	case IE_NOINSTANCE:
 		mes "The memorial dungeon Endless Tower does not exist.";
 		mes "The party leader did not generate the dungeon yet.";
 		close;
-	case 1:
+	case IE_NOMEMBER:
 		mes "You can enter the dungeon after making the party.";
 		close;
-	case 0:
+	case IE_OK:
 		mapannounce "e_tower", strcharinfo(0) +" of the party, "+ getpartyname( getcharid(1) ) +", is entering the dungeon, Endless Tower.",bc_map,"0x00ff99",FW_NORMAL,12;
 		if (getarg(1)) {
 			set etower_timer,gettimetick(2);

npc/instances/NydhoggsNest.txt

@@ -193,19 +193,19 @@ nyd_dun02,100,201,3	script	Yggdrasil Gatekeeper	111,8,8,{
 
 L_Enter:
 	switch(instance_enter("Nidhoggur's Nest")) {
-	case 3:
+	case IE_OTHER:
 		mes "[Yggdrasil Gatekeeper]";
 		mes "An unknown error has occurred.";
 		close;
-	case 2:
+	case IE_NOINSTANCE:
 		mes "[Yggdrasil Gatekeeper]";
 		mes "You didn't ask to be admitted... You should accept admission first before entering.";
 		close;
-	case 1:
+	case IE_NOMEMBER:
 		mes "[Yggdrasil Gatekeeper]";
 		mes "Where are the other servants, so you can work together? Each servant cannot be admitted here individually...";
 		close;
-	case 0:
+	case IE_OK:
 		mapannounce "nyd_dun02", getpartyname(getcharid(1))+"'s party member "+strcharinfo(0)+" has entered Nidhoggur's Nest.",bc_map,"0x00ff99";
 		if (checkquest(3135) == -1) setquest 3135;
 		if (checkquest(3136) == -1) setquest 3136;

npc/instances/OrcsMemory.txt

@@ -85,17 +85,17 @@ gef_fild10,242,202,0	script	Dimensional Gorge Piece	406,{
 	close;
 L_Enter:
 	switch(instance_enter("Orc's Memory")) {
-	case 3:
+	case IE_OTHER:
 		mes "An unknown error has occurred.";
 		close;
-	case 2:
+	case IE_NOINSTANCE:
 		mes "Memorial Dungeon Orc's Memory does not exist.";
 		mes "Memorial Dungeon has been destroyed by the Party Leader, or because of the time limit. Please try again after 2 hours.";
 		close;
-	case 1:
+	case IE_NOMEMBER:
 		mes "Only a member of the party can enter the Memorial Dungeon.";
 		close;
-	case 0:
+	case IE_OK:
 		mapannounce "gef_fild10", getpartyname( getcharid(1) ) +" party's member "+strcharinfo(0)+" has entered the Orc's Memory.",bc_map,"0x00ff99";
 		if (checkquest(12059) == -1) setquest 12059;
 		//warp "1@orcs",179,15;

npc/instances/SealedShrine.txt

@@ -215,15 +215,15 @@ monk_test,306,151,3	script	Grave of Baphomet#edq	111,{
 
 	if (.@ins_bapho_check == -1) {
 		switch(instance_enter("Sealed Catacomb")) {
-		case 3:
-		case 2:
+		case IE_OTHER:
+		case IE_NOINSTANCE:
 			mes "It's cold to the touch. It doesn't respond.";
 			close;
-		case 1:
+		case IE_NOMEMBER:
 			mes "[Friar Patrick]";
 			mes "To enter this dangerous place, you can't go alone. Come again after you join a party.";
 			close;
-		case 0:
+		case IE_OK:
 			mapannounce "monk_test","[" + strcharinfo(0) + "] member of the [" + getpartyname(.@party_id) + "] party has entered the Sealed Shrine.",bc_map,"0x00ff99";
 			setquest 3040;
 			//warp "1@cata",100,224;

npc/re/instances/BakonawaLake.txt

@@ -75,19 +75,19 @@ ma_scene01,174,179,4	script	Taho	541,{
 			close;
 		case 2:
 			switch(instance_enter(.@md_name$)) {
-			case 3:
+			case IE_OTHER:
 				mes "[Taho]";
 				mes "An unknown error occurred.";
 				close;
-			case 2:
+			case IE_NOINSTANCE:
 				mes "[Taho]";
 				mes "The rope hasn't been weaved yet. Wait a little.";
 				close;
-			case 1:
+			case IE_NOMEMBER:
 				mes "[Taho]";
 				mes "Civilians cannot enter.";
 				close;
-			case 0:
+			case IE_OK:
 				mapannounce "ma_scene01","A party member, "+strcharinfo(0)+" of the party "+getpartyname(.@party_id)+" is entering the dungeon, "+.@md_name$+".",bc_map,"0x00ff99"; //FW_NORMAL 12 0 0
 				setquest 12278;
 				//warp "1@ma_b",64,51;

npc/re/instances/BangungotHospital.txt

@@ -283,21 +283,21 @@ L_Enter:
 		end;
 	case 2:
 		switch(instance_enter(.@md_name$)) {
-		case 3:
+		case IE_OTHER:
 			mes "[Nurse Maenne]";
 			mes "A critical situation has happened.";
 			mes "You can't go up to the 2nd floor.";
 			close2;
 			cutin "",255;
 			end;
-		case 2:
+		case IE_NOINSTANCE:
 			mes "[Nurse Maenne]";
 			mes "You can't go up to";
 			mes "the 2nd floor now.";
 			close2;
 			cutin "",255;
 			end;
-		case 1:
+		case IE_NOMEMBER:
 			mes "[Nurse Maenne]";
 			mes "It's too dangerous to go";
 			mes "up to the 2nd floor alone.";
@@ -306,7 +306,7 @@ L_Enter:
 			close2;
 			cutin "",255;
 			end;
-		case 0:
+		case IE_OK:
 			mapannounce "ma_dun01", getpartyname(getcharid(1))+" party's "+strcharinfo(0)+" member entered "+.@md_name$+".",bc_map,"0x00ff99";
 			if (getarg(1)) {
 				if (checkquest(9223) > -1) {

npc/re/instances/BuwayaCave.txt

@@ -127,17 +127,17 @@ OnTouch:
 	switch(select("Enter.:Turn back.")) {
 	case 1:
 		switch(instance_enter("Buwaya Cave")) {
-		case 3:
+		case IE_OTHER:
 			mes "[Guard]";
 			mes "Oh, now is not a good time.";
 			mes "Please try again a moment later.";
 			close;
-		case 2:
-		case 1:
+		case IE_NOINSTANCE:
+		case IE_NOMEMBER:
 			mes "[Guard]";
 			mes "This place is dangerous. Please do not enter.";
 			close;
-		case 0:
+		case IE_OK:
 			mapannounce "ma_fild02",getpartyname(getcharid(1))+" party's "+strcharinfo(0)+" member began hunting Buwaya in Buwaya Cave.",bc_map,"0x00ff99"; //FW_NORMAL 12 0 0
 			setquest 4229;
 			//warp "1@ma_c",35,57;

npc/re/instances/EclageInterior.txt

@@ -75,13 +75,13 @@ ecl_hub01,130,15,0	script	It is closed shut.	844,{
 				close;
 			}
 			switch (instance_enter(.@md_name$)) {
-			case 3:
+			case IE_OTHER:
 				mes "An unknown error has occurred.";
 				close;
-			case 2:
+			case IE_NOINSTANCE:
 				mes "It is closed shut.";
 				close;
-			case 0:
+			case IE_OK:
 				mapannounce "ecl_hub01",getpartyname(.@party_id) + " Party leader " + strcharinfo(0) + " is entering " + .@md_name$,bc_map,"0x00ff99";
 				end;
 			default:

npc/re/instances/HazyForest.txt

@@ -140,22 +140,22 @@ bif_fild01,161,355,0	script	Log Tunnel	844,{
 	if(select("Enter the tunnel.:Give up.") == 2)
 		close;
 	switch(instance_enter("Mistwood Maze")) {
-	case 3:
+	case IE_OTHER:
 		mes "[Laphine Soldier]";
 		mes "Something doesn't feel right. Looks like something dangerous is going on, so you'd better turn back today.";
 		close;
-	case 2:
+	case IE_NOINSTANCE:
 		mes "You try to crawl into the log, but some mysterious power pushes you back with a gush of wind.";
 		mes "It seems like you can't force your way into the forest.";
 		close;
-	case 1:
+	case IE_NOMEMBER:
 		mes "[Laphine Soldier]";
 		mes "Hey, look!";
 		mes "Are you going alone?";
 		mes "That's impossible. Too rash.";
 		mes "Team up with some friends and go together!";
 		close;
-	case 0:
+	case IE_OK:
 		if (checkquest(7211,PLAYTIME) == 2) erasequest 7211;
 		if (checkquest(7211,PLAYTIME) == -1) setquest 7211;
 		mapannounce "bif_fild01",getpartyname(getcharid(1))+" party's "+strcharinfo(0)+" member is entering the Mistwood Maze.",bc_map,"0x00ff99"; //FW_NORMAL 12 0 0

npc/re/instances/MalangdoCulvert.txt

@@ -433,17 +433,17 @@ mal_in01,160,34,4	script	Missing, the Cleaner	545,{
 	end;
 L_Enter:
 	switch(instance_enter("Culvert")) {
-	case 3:
+	case IE_OTHER:
 		mes "An unknown error has occurred.";
 		close;
-	case 2:
+	case IE_NOINSTANCE:
 		mes "The gate to the Culvert is still closed.";
 		mes "You must wait until you are able to enter or find a party leader who can create the instance.";
 		close;
-	case 1:
+	case IE_NOMEMBER:
 		mes "Only party members can participate.";
 		close;
-	case 0:
+	case IE_OK:
 		mapannounce "mal_in01", strcharinfo(0)+" of the party "+getpartyname(getcharid(1))+" is entering the Culvert.",bc_map,"0x00ff99";
 		if (checkquest(12254) == -1) setquest 12254;
 		//warp "1@pump",63,98;

npc/re/instances/OctopusCave.txt

@@ -120,18 +120,18 @@ mal_dun01,153,237,5	script	Weird Entrance	844,{
 	case 1:
 		if (countitem(6442)) {
 			switch(instance_enter("Octopus Cave")) {
-			case 3:
+			case IE_OTHER:
 				mes "[Starfish]";
 				mes "Ah, now is not the time...";
 				mes "Would you come back later? Hehe.";
 				close;
-			case 2:
-			case 1:
+			case IE_NOINSTANCE:
+			case IE_NOMEMBER:
 				mes "[Starfish]";
 				mes "There is a secret with that entrance.";
 				mes "So, please be careful with it, will ya? Hehe.";
 				close;
-			case 0:
+			case IE_OK:
 				mapannounce "mal_dun01", getpartyname(getcharid(1))+" party's "+strcharinfo(0)+" member started to hunt the Octopus!",bc_map,"0x00ff99";
 				if (checkquest(4197) == -1) setquest 4197;
 				//warp instance_mapname("1@cash"),199,99;

npc/re/instances/OldGlastHeim.txt

@@ -52,17 +52,17 @@ glast_01,204,273,6	script	Hugin#ghinstance	755,{
 			close;
 		case 2:
 			switch(instance_enter(.@md_name$)) {
-			case 3:
+			case IE_OTHER:
 				mes "An unknown error has occurred.";
 				close;
-			case 2:
+			case IE_NOINSTANCE:
 				mes "The memorial dungeon "+.@md_name$+" does not exist.";
 				mes "The party leader did not generate the dungeon yet.";
 				close;
-			case 1:
+			case IE_NOMEMBER:
 				mes "Only the registered members can enter the instance "+.@md_name$+".";
 				close;
-			case 0:
+			case IE_OK:
 				mapannounce "glast_01",strcharinfo(0)+", member of the party "+.@p_name$+" entered the instance "+.@md_name$+".",bc_map,"0x00ff99";
 				setquest 12317;
 				setquest 12318;

npc/re/instances/SaraMemory.txt

@@ -196,17 +196,17 @@ dali,139,118,4	script	Dimensional Device#sara	10007,{
 			close;
 		case 2:
 			switch(instance_enter(.@md_name$)) {
-			case 3:
+			case IE_OTHER:
 				mes "An unknown error has occurred.";
 				close;
-			case 2:
+			case IE_NOINSTANCE:
 				mes "The memorial dungeon "+.@md_name$+" does not exist.";
 				mes "The party leader did not generate the dungeon yet.";
 				close;
-			case 1:
+			case IE_NOMEMBER:
 				mes "Only the registered members can enter the instance "+.@md_name$+".";
 				close;
-			case 0:
+			case IE_OK:
 				mapannounce "dali",strcharinfo(0)+", member of the party "+.@p_name$+" entered the instance "+.@md_name$+".",bc_map,"0x00ff99";
 				setquest 15002;
 				end;

npc/re/instances/WolfchevLaboratory.txt

@@ -877,7 +877,7 @@ lhz_dun04,147,279,0	script	Laboratory Entrance#memo	CLEAR_NPC,{
 			mes "You have stopped entering to Wolfchev's laboratory.";
 			close;
 		}
-		if (instance_enter("Wolfchev's Laboratory") != 0) {  // probably missing failure cases
+		if (instance_enter("Wolfchev's Laboratory") != IE_OK) {  // probably missing failure cases
 			mes "^FF0000Warning^000000";
 			mes ""+ strcharinfo(0) +". . .";
 			mes "^FF0000Unregistered personnel^000000";

src/map/instance.c

@@ -645,77 +645,82 @@ int instance_destroy(unsigned short instance_id)
 	return 0;
 }
 
-/*==========================================
- * Allows a user to enter an instance
- *------------------------------------------*/
-int instance_enter(struct map_session_data *sd, unsigned short instance_id, const char *name)
-{
-	struct instance_db *db = instance_searchname_db(name);
-
-	nullpo_retr(-1, sd);
-
-	if (db == NULL)
-		return 2;
-
-	return instance_enter_position(sd, instance_id, name, db->enter.x, db->enter.y);
-}
-
 /*==========================================
  * Warp a user into instance
  *------------------------------------------*/
-int instance_enter_position(struct map_session_data *sd, unsigned short instance_id, const char *name, short x, short y)
+enum e_instance_enter instance_enter(struct map_session_data *sd, unsigned short instance_id, const char *name, short x, short y)
 {
-	struct instance_data *im = &instance_data[instance_id];
-	struct instance_db *db = instance_searchname_db(name);
+	struct instance_data *im = NULL;
+	struct instance_db *db = NULL;
 	struct party_data *p = NULL;
 	struct guild *g = NULL;
+	enum instance_mode mode;
 	int16 m;
 
-	nullpo_retr(-1, sd);
-	nullpo_retr(3, db);
+	nullpo_retr(IE_OTHER, sd);
+	
+	if( (db = instance_searchname_db(name)) == NULL ){
+		ShowError( "instance_enter: Unknown instance \"%s\".\n", name );
+		return IE_OTHER;
+	}
+	
+	// If one of the two coordinates was not given or is below zero, we use the entry point from the database
+	if( x < 0 || y < 0 ){
+		x = db->enter.x;
+		y = db->enter.y;
+	}
+	
+	// Check if it is a valid instance
+	if( instance_id == 0 ){
+		// im will stay NULL and by default party checks will be used
+		mode = IM_PARTY;
+	}else{
+		im = &instance_data[instance_id];
+		mode = im->mode;
+	}
 
-	switch(instance_data[instance_id].mode) {
+	switch(mode) {
 		case IM_NONE:
 			break;
 		case IM_CHAR:
 			if (sd->instance_id == 0) // Player must have an instance
-				return 2;
+				return IE_NOINSTANCE;
 			if (im->owner_id != sd->status.char_id)
-				return 3;
+				return IE_OTHER;
 			break;
 		case IM_PARTY:
 			if (sd->status.party_id == 0) // Character must be in instance party
-				return 1;
+				return IE_NOMEMBER;
 			if ((p = party_search(sd->status.party_id)) == NULL)
-				return 1;
-			if (p->instance_id == 0) // Party must have an instance
-				return 2;
+				return IE_NOMEMBER;
+			if (p->instance_id == 0 || im == NULL) // Party must have an instance
+				return IE_NOINSTANCE;
 			if (im->owner_id != p->party.party_id)
-				return 3;
+				return IE_OTHER;
 			break;
 		case IM_GUILD:
 			if (sd->status.guild_id == 0) // Character must be in instance guild
-				return 1;
+				return IE_NOMEMBER;
 			if ((g = guild_search(sd->status.guild_id)) == NULL)
-				return 1;
+				return IE_NOMEMBER;
 			if (g->instance_id == 0) // Guild must have an instance
-				return 2;
+				return IE_NOINSTANCE;
 			if (im->owner_id != g->guild_id)
-				return 3;
+				return IE_OTHER;
 			break;
 	}
 
 	if (im->state != INSTANCE_BUSY)
-		return 3;
+		return IE_OTHER;
 	if (im->type != db->id)
-		return 3;
+		return IE_OTHER;
 
 	// Does the instance match?
 	if ((m = instance_mapname2mapid(StringBuf_Value(db->enter.mapname), instance_id)) < 0)
-		return 3;
+		return IE_OTHER;
 
 	if (pc_setpos(sd, map_id2index(m), x, y, CLR_OUTSIGHT))
-		return 3;
+		return IE_OTHER;
 
 	// If there was an idle timer, let's stop it
 	instance_stopidletimer(im, instance_id);
@@ -723,7 +728,7 @@ int instance_enter_position(struct map_session_data *sd, unsigned short instance
 	// Now we start the instance timer
 	instance_startkeeptimer(im, instance_id);
 
-	return 0;
+	return IE_OK;
 }
 
 /*==========================================
@@ -1005,7 +1010,7 @@ void do_reload_instance(void)
 					ShowError("do_reload_instance: Unexpected instance mode for instance %s (id=%u, mode=%u).\n", (db) ? StringBuf_Value(db->name) : "Unknown", map[sd->bl.m].instance_id, (unsigned short)im->mode);
 					continue;
 			}
-			if((db = instance_searchtype_db(im->type)) != NULL && !instance_enter(sd, instance_id, StringBuf_Value(db->name))) { // All good
+			if((db = instance_searchtype_db(im->type)) != NULL && !instance_enter(sd, instance_id, StringBuf_Value(db->name), -1, -1)) { // All good
 				clif_displaymessage(sd->fd, msg_txt(sd,515)); // Instance has been reloaded
 				instance_reqinfo(sd,instance_id);
 			} else // Something went wrong

src/map/instance.h

@@ -28,6 +28,13 @@ enum instance_mode {
 	IM_MAX,
 };
 
+enum e_instance_enter {
+	IE_OK = 0,
+	IE_NOMEMBER,
+	IE_NOINSTANCE,
+	IE_OTHER
+};
+
 struct s_instance_map {
 	int16 m, src_m;
 };
@@ -68,8 +75,7 @@ void instance_getsd(unsigned short instance_id, struct map_session_data **sd, en
 
 int instance_create(int owner_id, const char *name, enum instance_mode mode);
 int instance_destroy(unsigned short instance_id);
-int instance_enter(struct map_session_data *sd, unsigned short instance_id, const char *name);
-int instance_enter_position(struct map_session_data *sd, unsigned short instance_id, const char *name, short x, short y);
+enum e_instance_enter instance_enter(struct map_session_data *sd, unsigned short instance_id, const char *name, short x, short y);
 int instance_reqinfo(struct map_session_data *sd, unsigned short instance_id);
 int instance_addusers(unsigned short instance_id);
 int instance_delusers(unsigned short instance_id);

src/map/script.c

@@ -19170,24 +19170,27 @@ BUILDIN_FUNC(instance_destroy)
 /*==========================================
  * Warps player to instance
  * Results:
- *	0: Success
- *	1: Character not in party/guild (for party/guild type instances)
- *	2: Character/Party/Guild doesn't have instance
- *	3: Other errors (instance not in DB, instance doesn't match with character/party/guild, etc.)
+ *	IE_OK: Success
+ *	IE_NOMEMBER: Character not in party/guild (for party/guild type instances)
+ *	IE_NOINSTANCE: Character/Party/Guild doesn't have instance
+ *	IE_OTHER: Other errors (instance not in DB, instance doesn't match with character/party/guild, etc.)
  *------------------------------------------*/
 BUILDIN_FUNC(instance_enter)
 {
 	struct map_session_data *sd = NULL;
 	int x = script_hasdata(st,3) ? script_getnum(st, 3) : -1;
 	int y = script_hasdata(st,4) ? script_getnum(st, 4) : -1;
+	unsigned short instance_id;
+
+	if (script_hasdata(st, 6))
+		instance_id = script_getnum(st, 6);
+	else
+		instance_id = script_instancegetid(st);
 
 	if (!script_charid2sd(5,sd))
 		return SCRIPT_CMD_FAILURE;
 
-	if (x != -1 && y != -1)
-		script_pushint(st, instance_enter_position(sd, script_instancegetid(st), script_getstr(st, 2), x, y));
-	else
-		script_pushint(st, instance_enter(sd, script_instancegetid(st), script_getstr(st, 2)));
+	script_pushint(st, instance_enter(sd, instance_id, script_getstr(st, 2), x, y));
 
 	return SCRIPT_CMD_SUCCESS;
 }
@@ -22535,7 +22538,7 @@ struct script_function buildin_func[] = {
 	BUILDIN_DEF(instance_create,"s??"),
 	BUILDIN_DEF(instance_destroy,"?"),
 	BUILDIN_DEF(instance_id,""),
-	BUILDIN_DEF(instance_enter,"s???"),
+	BUILDIN_DEF(instance_enter,"s????"),
 	BUILDIN_DEF(instance_npcname,"s?"),
 	BUILDIN_DEF(instance_mapname,"s?"),
 	BUILDIN_DEF(instance_warpall,"sii?"),

src/map/script_constants.h

@@ -3185,6 +3185,12 @@
 	export_constant(STOR_MODE_NONE);
 	export_constant(STOR_MODE_GET);
 	export_constant(STOR_MODE_PUT);
+	
+	/* instance enter */
+	export_constant(IE_OK);
+	export_constant(IE_NOMEMBER);
+	export_constant(IE_NOINSTANCE);
+	export_constant(IE_OTHER);
 
 	#undef export_constant