diff options
| -rw-r--r-- | Changelog-Trunk.txt | 4 | ||||
| -rw-r--r-- | doc/script_commands.txt | 108 | ||||
| -rw-r--r-- | src/map/instance.c | 13 | ||||
| -rw-r--r-- | src/map/script.c | 4 |
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; } |