* Updated/revised description of instance-related script commands (bugreport:4880).

- Fixed 'instance_create' would return -4 (party already instancing) when the requested party was not found.
- 'instance_create' return value -2 now means 'party not found' rather than 'missing parameter'.

git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@14809 54d463be-8e91-2dee-dedb-b68131a5f0ec

4 files changed, 89 insertions, 40 deletions

diff --git a/Changelog-Trunk.txt b/Changelog-Trunk.txt
index b81de37a7..7a6707d6c 100644
--- a/Changelog-Trunk.txt
+++ b/Changelog-Trunk.txt
@@ -1,5 +1,9 @@
 Date	Added
 
+2011/05/08
+	* Updated/revised description of instance-related script commands (bugreport:4880). [Ai4rei]
+	- Fixed 'instance_create' would return -4 (party already instancing) when the requested party was not found.
+	- 'instance_create' return value -2 now means 'party not found' rather than 'missing parameter'.
 2011/05/01
 	* Removed functions 'decode_zip' (ancient) and 'encode_zip' (from r824) from grfio. These were outdated copies of zlib's 'uncompress' and 'compress' respectively (related r1530 and r5152). [Ai4rei]
 	* Removed auto-add feature from mapindex code, as map indexes are used for save data, thus need to be constant across server starts (since r4726). [Ai4rei]
diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 2e930e8a3..a8f3fb63c 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -4,7 +4,7 @@
 //= A reference manual for the eAthena scripting language.
 //= Commands are sorted depending on their functionality.
 //===== Version ===========================================
-//= 3.41.20110427
+//= 3.42.20110508
 //=========================================================
 //= 1.0 - First release, filled will as much info as I could
 //=       remember or figure out, most likely there are errors,
@@ -171,6 +171,9 @@
 //= 3.41.20110427
 //=       Updated description of 'itemheal' primarily to remove overhead and lies
 //=       about client effects. [Ai4rei]
+//= 3.42.20110508
+//=       Updated description of all instance commands to reflect actual behavior.
+//=       [Ai4rei]
 //=========================================================
 
 This document is a reference manual for all the scripting commands and functions 
@@ -5542,7 +5545,7 @@ currently ignored by the client and appears always green.
 5,1.- End of time-related commands
 //
 
-*announce "<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}}};
+*announce "<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}};
 
 This command will broadcast a message to all or most players, similar to 
 @kami/@kamib GM commands.
@@ -6766,18 +6769,17 @@ This will open a book item at the specified page
 ========================
 ---------------------------------------
 
-*instance_create("<Instance Name>",<Party ID>,<Instance>)
+*instance_create("<instance name>",<party id>);
 
-Create an instance using the name "<Instance Name>" for the Party of <Party ID>.
-Instance ID currently will only be ID_ENDLESS (5) or ID_CATACOMBS (6)
-Most Instance_* commands are used in conjunction with this command and depend
+Create an instance using the name "<instance name>" for the Party of <party id>.
+Most instance_* commands are used in conjunction with this command and depend
 on the ID this command returns.
 
 Example: 
 	// Store the Party ID of the invoking character.
 	set .@party_id, getcharid(1);
 	// Attempt to create an instance using that party ID.
-	set .@id, instance_create("Endless Tower", .@party_id, ID_ENDLESS);
+	set .@id, instance_create("Endless Tower", .@party_id);
 	if (.@id == -1) { // Party ID is in use by another instance.
 		...
 	}
@@ -6786,67 +6788,111 @@ Example:
 	}
 ---------------------------------------
 
-*instance_destroy(<Instance ID>)
+*instance_destroy {<instance id>};
 
-Destroys instance with the ID <Instance ID>.
+Destroys instance with the ID <instance id>. If no ID is specified, the instance,
+the script is attached to, is used. If the script is not attached to an instance,
+the instance of the currently attached player's party is used. If no player is
+currently attached, the command fails and causes the script to halt.
 
 ---------------------------------------
 
-*instance_attachmap(<Instance ID>,"<Map Name>")
-*instance_detachmap(<Instance ID>,"<Map Name>")
+*instance_attachmap("<map name>",<instance id>{,<use base name>});
+
+Attaches the map "<map name>" to the instance specified with <instance id>. The
+optional parameter specifies, whether a map requires emulation for instancing (1)
+or not (0 = default).
 
-Attach or detach the map "<Map Name>" to the instance with the <Instance ID>.
+Returns the resulting map name on success or an empty string on failure.
 
 ---------------------------------------
 
-*instance_init(<Instance ID>);
+*instance_detachmap "<map name>"{,<instance id>};
 
-Initiate the instance of <Instance ID>.
+Detach the map "<map name>" to the instance with the <instance id>. If no ID is
+specified, the instance, the script is attached to, is used. If the script is not
+attached to an instance, the instance of the currently attached player's party is
+used. If no player is currently attached, the command fails and causes the script
+to halt.
 
 ---------------------------------------
 
-*instance_announce <Instance ID>,"<text>",<flag>{,<color>};
+*instance_init <instance id>;
 
-Works like announce, but has the <Instance ID> parameter, where 0 = active instance?
+Initializes the instance given by <instance id>. This copies all NPCs from the
+source maps to the instanced maps.
 
 ---------------------------------------
 
-*instance_attach(<Instance ID>);
+*instance_announce <instance id>,"<text>",<flag>{,<fontColor>{,<fontType>{,<fontSize>{,<fontAlign>{,<fontY>}}}}};
 
-Attaches a script to the provided <Instance ID>?
+Works like announce, but has the <instance id> parameter. If instance id is 0, the
+instance, the script is attached to, is used. If the script is not attached to an
+instance, the instance of the currently attached player's party is used. If no
+player is currently attached, the command fails and causes the script to halt.
 
 ---------------------------------------
 
-*instance_npcname("<NPC Name>",<Instance ID>)
+*instance_attach <instance id>;
 
-Retrieve the unique name given to a copy of an NPC for an instance, the given
-"<NPC Name>" that belongs to instance <Instance ID>. Can be used with such commands
-as enablenpc and disablenpc, donpcevent, etc.
+Attaches the current script to the instance given by <instance id>.
 
 ---------------------------------------
 
-*has_instance("<Map Name>")
+*instance_npcname("<npc name>"{,<instance id>});
 
-Check if the player has been queued for the <Map Name> instance.
+Retrieves the unique name given to a copy of an NPC given by "<npc name>" in an
+instance specified <instance id>. If no ID is specified, the instance, the script
+is attached to, is used. If the script is not attached to an instance, the
+instance of the currently attached player's party is used. If no player is
+currently attached, the command fails and causes the script to halt.
 
 ---------------------------------------
 
-*instance_id(<?>)
+*has_instance("<map name>"{,<instance id>});
+
+Checks whether or not the given map belongs to specified instance. If no ID is
+specified, the instance, the script is attached to, is used. If the script is not
+attached to an instance, the instance of the currently attached player's party
+is used. If no player is currently attached, the command fails and causes the
+script to halt.
 
-Apparently returns the ID the player is currently attached too.
+Returns the name of the instanced map on success, otherwise an empty string.
 
 ---------------------------------------
 
-*instance_warpall "<Map Name>",<x>,<y>;
+*instance_id({<type>});
 
-Warp all players in the instance to <map name> and given coordinates.
+Retrieves the instance id, depending on <type>. If type is not given, it defaults
+to 0.
+
+Type:
+    0 - Instance ID the script is attached to.
+    1 - Instance ID of the currently attached player's party.
 
 ---------------------------------------
 
-*instance_set_timeout <Time1>,<Time2>,<Instance ID>;
+*instance_warpall "<map name>",<x>,<y>{,<instance id>};
+
+Warps all players in the instance <instance id> to <map name> at given
+coordinates. If no ID is specified, the instance, the script is attached to,
+is used. If the script is not attached to an instance, the instance of the
+currently attached player's party is used. If no player is currently attached,
+the command fails and causes the script to halt.
+
+---------------------------------------
+
+*instance_set_timeout <alive timeout>,<idle timeout>{,<instance id>};
+
+Sets the timeout values for an instance given by <instance id>. If no ID is
+specified, the instance, the script is attached to, is used. If the script is
+not attached to an instance, the instance of the currently attached player's
+party is used. If no player is currently attached, the command fails and causes
+the script to halt.
 
-Lifetime of <Time1> for <Instance ID>, while <Time2> is how long until the 
-instance times out while inactive. 
+Parameter <alive timeout> specifies the total amount of time the instance will
+exist. Parameter <idle timeout> specifies how long players have, when they are
+outside of the instance, until it is destroyed.
 
 ---------------------------------------
 
diff --git a/src/map/instance.c b/src/map/instance.c
index 6fa3a2c0a..e9ff2b409 100644
--- a/src/map/instance.c
+++ b/src/map/instance.c
@@ -31,22 +31,21 @@ struct s_instance instance[MAX_INSTANCE];
 /*--------------------------------------
  * name : instance name
  * Return value could be
- * -4 = already exists | -3 = no free instances | -2 = missing parameter | -1 = invalid type
+ * -4 = already exists | -3 = no free instances | -2 = party not found | -1 = invalid type
  * On success return instance_id
  *--------------------------------------*/
 int instance_create(int party_id, const char *name)
 {
 	int i;
-	struct party_data *p = NULL;
+	struct party_data* p;
 
-	if( !party_id || !name )
+	if( ( p = party_search(party_id) ) == NULL )
 	{
-		ShowError("map_instance_create: missing parameter.\n");
+		ShowError("instance_create: party %d not found for instance '%s'.\n", party_id, name);
 		return -2;
 	}
 
-	p = party_search(party_id);
-	if( !p || p->instance_id )
+	if( p->instance_id )
 		return -4; // Party already instancing
 
 	// Searching a Free Instance
@@ -54,7 +53,7 @@ int instance_create(int party_id, const char *name)
 	ARR_FIND(1, MAX_INSTANCE, i, instance[i].state == INSTANCE_FREE);
 	if( i == MAX_INSTANCE )
 	{
-		ShowError("map_instance_create: no free instances, consider increasing MAX_INSTANCE.\n");
+		ShowError("instance_create: no free instances, consider increasing MAX_INSTANCE.\n");
 		return -3;
 	}
 
diff --git a/src/map/script.c b/src/map/script.c
index 4f565b9ed..0b6732f08 100644
--- a/src/map/script.c
+++ b/src/map/script.c
@@ -14360,11 +14360,11 @@ BUILDIN_FUNC(instance_create)
 	}
 	else if( res < 0 )
 	{
-		char *err;
+		const char *err;
 		switch(res)
 		{
 		case -3: err = "No free instances"; break;
-		case -2: err = "Missing parameter"; break;
+		case -2: err = "Invalid party ID"; break;
 		case -1: err = "Invalid type"; break;
 		default: err = "Unknown"; break;
 		}