Unify specialeffect, convert legacy scripts (#1746)

* allow to use specialeffect() on any unit, and to send to any player

* update the documentation for specialeffect()

* remove specialeffect2 from databases

* remove specialeffect2 from npcs

* remove misceffect from npcs

* convert specialeffect calls with strings to use GID

* add missing constants to specialeffect calls

* flag specialeffect2() as deprecated

* flag misceffect() as deprecated

1 files changed, 36 insertions, 15 deletions

diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 861b9cc59..34089f767 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -5819,7 +5819,8 @@ map as the invoking character.
 
 ---------------------------------------
 
-*specialeffect(<effect number>{, <send_target>{, "<NPC Name>"}})
+*specialeffect(<effect number>{, <send_target>{, <unit id>{, <account id>}}})
+*specialeffect(<effect number>{, <send_target>{, "<NPC Name>"{, <account id>}}})
 
 This command will display special effect with the given number, centered 
 on the specified NPCs coordinates, if any. For a full list of special 
@@ -5832,25 +5833,40 @@ NPC specified does not exist, the command will do nothing. When specifying
 an NPC, <send_target> must be specified when specifying an <NPC Name>, 
 specifying AREA will retain the default behavior of the command.
 
-	// this will make the NPC "John Doe#1"
-	// show the effect "EF_HIT1" specified by
-	// Jane Doe. I wonder what John did...
-	mes("[Jane Doe]");
-	mes("Well, I never!");
+<unit id> behaves like <NPC Name> except it can display the effect on
+any kind of unit, not just NPC, by specifying its GID.
+
+When <send_target> is SELF you can specify which player to send the effect
+to by passing <account id>.
+
+Example usage:
+
+	// To make a NPC do an effect and show it to everyone:
 	specialeffect(EF_HIT1, AREA, "John Doe#1");
-	close();
+
+	// To make a player do an effect and show it to everyone:
+	specialeffect(EF_HIT1, AREA, getcharid(CHAR_ID_ACCOUNT, "player"));
+
+	// To make a NPC do an effect and show it only to the attached player:
+	specialeffect(EF_HIT1, SELF, "John Doe#1");
+
+	// To make a NPC do an effect and show it only to another player:
+	specialeffect(EF_HIT1, SELF, "John Doe#1", getcharid(CHAR_ID_ACCOUNT, "player"));
 
 ---------------------------------------
 
 *specialeffect2(<effect number>{, <send_target>{, "<Player Name>"}})
 
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+    @ /!\ This command is deprecated @
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
 This command behaves identically to the specialeffect(), but the effect
 will be centered on the invoking character's sprite.
 
-<Player name> parameter will display <effect number> on another Player 
-than the one currently attached to the script. Like with specialeffect(),
-when specifying a player, <send_target> must be supplied, specifying AREA 
-will retain the default behavior of the command.
+This command is deprecated and it should not be used in new scripts, as it is
+likely to be removed at a later time. Please use specialeffect instead,
+ie: specialeffect(<effect number>, <send_target>, playerattached())
 
 ---------------------------------------
 
@@ -5950,7 +5966,7 @@ target in autobonus() and autobonus3()).
 //Grants a 1% chance of starting the state "all stats +10" for 10 seconds 
 //when using weapon or misc attacks (both melee and ranged skills) and 
 //shows a special effect when the bonus is active.
-	autobonus("{ bonus(bAllStats, 10); }", 10, 10000, BF_WEAPON|BF_MISC, "{ specialeffect2(EF_FIRESPLASHHIT); }");
+	autobonus("{ bonus(bAllStats, 10); }", 10, 10000, BF_WEAPON|BF_MISC, "{ specialeffect(EF_FIRESPLASHHIT, AREA, playerattached()); }");
 
 ---------------------------------------
 
@@ -7619,6 +7635,10 @@ without event labels. If specified name is not found, command does nothing.
 
 *misceffect(<effect number>)
 
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+    @ /!\ This command is deprecated @
+    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
 This command, if run from an NPC object that has a sprite, will call up a 
 specified effect number, centered on the NPC sprite. If the running code 
 does not have an object ID (a 'floating' NPC) or is not running from an 
@@ -7627,8 +7647,9 @@ character who's RID got attached to the script, if any. For usable item
 scripts, this command will create an effect centered on the player using 
 the item.
 
-A full list of known effects is found in 'doc/effect_list.txt'. The list 
-of those that actually work may differ greatly between client versions.
+This command is deprecated and it should not be used in new scripts, as it is
+likely to be removed at a later time. Please use specialeffect instead,
+ie: specialeffect(<effect number>, <send target>, <unit id>)
 
 ---------------------------------------
 
@@ -7753,7 +7774,7 @@ OnInit:
 	bindatcmd("test", strnpcinfo(NPC_NAME_UNIQUE)+"::OnAtcommand");
 	end;
 OnAtcommand:
-	specialeffect2(EF_ANGEL2);
+	specialeffect(EF_ANGEL2, AREA, playerattached());
 	end;
 }